Build an App with Claude Code: Terminal Setup Guide
Using terminal AI tools without proper guardrails often leads to runaway context windows, unexpected file edits, and wasted API spend. This guide is for developers and software engineers who want to build an app with Claude Code while maintaining tight control over project architecture. By following this workflow, you will configure the official native environment, establish persistent project memory, and structure a clean codebase ready for automated agent testing.
Before you start
- A Linux terminal (Ubuntu 20.04+ or Debian 10+)
- curl, git, and python3 installed
- An Anthropic account (Claude Pro, Max, or an Anthropic API key)
Understanding Claude Code Requirements
Claude Code operates as an autonomous command-line agent rather than a passive code completion engine. It reads your local project files, executes shell commands, inspects test outcomes, and iteratively refactors source files based on terminal feedback.
Using this tool requires an active Claude Pro or Max subscription, or an Anthropic Console account configured with API credits. The current platform relies on an official native installer that handles its own background updates independently.
Installing Claude Code
Anthropic distributes Claude Code through an automated installation script that deploys the native executable straight into your user profile. This avoids global runtime dependencies and isolates the binary inside your local environment.
To perform the tested setup, execute the download script below, export the local binary directory into your shell environment, and check the installed release. In our Debian verification run, this completed cleanly and reported the version number as expected.
# Download and run the official Anthropic native installer
curl -fsSL https://claude.ai/install.sh | bash
# Ensure ~/.local/bin is available in the current shell session
export PATH="$HOME/.local/bin:$PATH"
# Verify Claude Code installation
claude --version
Output from our test run
$ curl -fsSL https://claude.ai/install.sh | bash
Setting up Claude Code...
✔ Claude Code successfully installed!
Version: 2.1.296
Location: ~/.local/bin/claude
Next: Run claude --help to get started
⚠ Setup notes:
● Native installation exists but ~/.local/bin is not in your PATH. Run:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> your shell config file && source your shell config file
✅ Installation complete!
$ export PATH="$HOME/.local/bin:$PATH"
$ claude --version
2.1.296 (Claude Code)
$Checking Environment Diagnostics
Before launching an active coding session, you should verify system health and runtime dependencies. The command-line tool includes a diagnostic utility designed to check network routes, bundled search components, and file access permissions.
Run the doctor command shown below to evaluate your current setup. Our test confirmed that the binary integrity and update channels checked out properly before connecting authentication.
# Run health diagnostics on the environment
claude doctor
Output from our test run
$ claude doctor
Claude Code doctor
Running: native (2.1.296)
Commit: fdb6c17a97b6
Platform: linux-x64
Path: /root/.local/share/claude/versions/2.1.296
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: none recorded
Managed settings (remote): not fetched — no usable credentials for the settings fetch
Organization policy: not fetched: no API key or claude.ai sign-in for the policy lookup (apiKeyHelper keys are n
ot used for it)
Remote Control
Remote Control requires a claude.ai subscription. Run claude auth login to sign in with your claude.ai account.
- Not signed in to claude.ai
- claude.ai subscription auth not active
- Sign-in is missing the user:profile scope
- Organization not resolved
- Remote Control availability could not be verified (no server response this session)
No installation issues found.
For a full setup checkup that can also fix issues, run /doctor in a Claude Code session.Setting Up the Project Directory
AI agents make rapid modifications to local files, making source control an absolute necessity before generating code. Initializing a clean git repository allows you to review granular diffs and roll back undesired changes with a standard checkout command.
Run the commands below to create the task-api folder, initialize repository tracking, and create an isolated Python virtual environment. We also append the environment directory to your ignore file to prevent virtual environment packages from cluttering your commits.
# Create project directory and initialize git repository
mkdir -p task-api && cd task-api && git init
# Set up a clean virtual environment and gitignore
python3 -m venv .venv && echo ".venv/" > .gitignore
Output from our test run
$ mkdir -p task-api && cd task-api && git init
Initialized empty Git repository in /root/task-api/.git/
$ python3 -m venv .venv && echo ".venv/" > .gitignore
$Creating CLAUDE.md for Project Memory
Without persistent guidance, agentic coding models can drift away from design requirements or introduce unapproved external libraries. Claude Code solves this by automatically reading a file named CLAUDE.md located in the root of your project before executing tasks.
Use this specification file to define baseline architectural decisions, preferred libraries, and standard test invocations. Keeping these requirements concise ensures the model retains essential rules without overloading your session context window.
# Project Guidelines: Task API
## Architecture
- Minimal REST API built with Python's built-in `http.server` or `FastAPI`
- Single file implementation preferred for core logic
- In-memory data store with structured JSON responses
## Commands
- Run tests: `python3 -m unittest discover tests`
- Lint: `python3 -m py_compile app.py`
## Conventions
- Write unit tests for all endpoints
- Keep functions small and modular
- Never install unnecessary external dependencies without prompting
Writing the Project Memory File
To establish project memory, write your instructions directly to CLAUDE.md in the project root. The sample definition restricts dependencies to standard library utilities and specifies exact unit testing commands.
Execute the file creation command below and commit the new specification alongside your ignore file. In our verification test, creating and staging these files passed cleanly on the initial commit.
# Write the persistent memory instructions
cat << 'EOF' > CLAUDE.md
# Project Guidelines: Task API
## Architecture
- Minimal REST API built with standard library http.server
- In-memory data store with JSON responses
## Commands
- Run tests: python3 -m unittest discover tests
- Run server: python3 app.py
## Conventions
- Write clean unit tests for all endpoints
- Keep code clear, standard-compliant, and well-structured
EOF
# Commit initial project guidelines
git add CLAUDE.md .gitignore && git commit -m "chore: initialize repository and guidelines"
Output from our test run
$ cat << 'EOF' > CLAUDE.md
> # Project Guidelines: Task API
>
> ## Architecture
> - Minimal REST API built with standard library http.server
> - In-memory data store with JSON responses
>
> ## Commands
> - Run tests: python3 -m unittest discover tests
> - Run server: python3 app.py
>
> ## Conventions
> - Write clean unit tests for all endpoints
> - Keep code clear, standard-compliant, and well-structured
> EOF
$ git add CLAUDE.md .gitignore && git commit -m "chore: initialize repository and guidelines"
[main (root-commit) 0c2c69c] chore: initialize repository and guidelines
2 files changed, 14 insertions(+)
create mode 100644 .gitignore
create mode 100644 CLAUDE.md
$How Authentication Works
Launching the tool with claude opens an authentication prompt. You can authenticate either by opening a browser session linked to your paid subscription account or by setting the ANTHROPIC_API_KEY environment variable in your terminal.
If you use an API key, export it directly in your terminal profile rather than passing sensitive keys as inline command arguments. Once authenticated, the CLI establishes your active session inside the target repository.
# Option A: Browser login (Pro or Max plan)
claude
# Option B: Anthropic Console API key
export ANTHROPIC_API_KEY="your-api-key-here"
claude
Essential Claude Code Slash Commands
Long agent sessions can accumulate thousands of tokens across iterative edits, driving up costs and degrading response precision. You can manage session scope using built-in interactive slash commands.
Use /cost to review token consumption and financial spend in real time. When shifting between major tasks, run /compact to condense conversation history or /clear to start fresh while retaining the rules defined in CLAUDE.md.
Verifying Our Baseline App Implementation
With guidelines active, Claude Code can construct your core application logic according to your specified architecture. The baseline implementation below sets up a lightweight REST service using the standard library http.server module.
The code provides a structured JSON response pattern, basic health checks, and initial in-memory task management without introducing third-party framework overhead.
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
tasks = []
class TaskHandler(BaseHTTPRequestHandler):
def _send_json(self, status, payload):
self.send_response(status)
self.send_header('Content-Type', 'application/json')
self.end_headers()
self.wfile.write(json.dumps(payload).encode('utf-8'))
def do_GET(self):
if self.path == '/tasks':
self._send_json(200, {'tasks': tasks})
elif self.path == '/health':
self._send_json(200, {'status': 'ok'})
else:
self._send_json(404, {'error': 'not found'})
def do_POST(self):
if self.path == '/tasks':
length = int(self.headers.get('Content-Length', 0))
body = json.loads(self.rfile.read(length).decode('utf-8'))
new_task = {'id': len(tasks) + 1, 'title': body.get('title', '')}
tasks.append(new_task)
self._send_json(201, new_task)
else:
self._send_json(404, {'error': 'not found'})
if __name__ == '__main__':
server = HTTPServer(('127.0.0.1', 8000), TaskHandler)
server.serve_forever()
Running Automated Verification Tests
In a complete workflow, automated test suites serve as the feedback mechanism for the agent loop. Claude Code runs the discovery command, reads any failures, and modifies code until all assertions pass.
We set up the baseline test file and executed the discovery command shown below. In our test environment, this verification run encountered a failure during execution, demonstrating why validating tests locally remains essential before accepting agent output.
# Create the application code to be tested
cat << 'EOF' > app.py
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
tasks = []
class TaskHandler(BaseHTTPRequestHandler):
def _send_json(self, status, payload):
self.send_response(status)
self.send_header('Content-Type', 'application/json')
self.end_headers()
self.wfile.write(json.dumps(payload).encode('utf-8'))
def do_GET(self):
if self.path == '/tasks':
self._send_json(200, {'tasks': tasks})
elif self.path == '/health':
self._send_json(200, {'status': 'ok'})
else:
self._send_json(404, {'error': 'not found'})
EOF
# Create the test file verifying initial task state
mkdir -p tests && cat << 'EOF' > tests/test_app.py
import unittest
from app import TaskHandler, tasks
class TestTaskApp(unittest.TestCase):
def test_tasks_initially_empty(self):
self.assertEqual(len(tasks), 0)
if __name__ == '__main__':
unittest.main()
EOF
# Execute the test suite
python3 -m unittest discover tests
Output from our test run
$ cat << 'EOF' > app.py
> from http.server import HTTPServer, BaseHTTPRequestHandler
> import json
>
> tasks = []
>
> class TaskHandler(BaseHTTPRequestHandler):
> def _send_json(self, status, payload):
> self.send_response(status)
> self.send_header('Content-Type', 'application/json')
> self.end_headers()
> self.wfile.write(json.dumps(payload).encode('utf-8'))
>
> def do_GET(self):
> if self.path == '/tasks':
> self._send_json(200, {'tasks': tasks})
> elif self.path == '/health':
> self._send_json(200, {'status': 'ok'})
> else:
> self._send_json(404, {'error': 'not found'})
> EOF
$ mkdir -p tests && cat << 'EOF' > tests/test_app.py
> import unittest
> from app import TaskHandler, tasks
>
> class TestTaskApp(unittest.TestCase):
> def test_tasks_initially_empty(self):Wrap-up
You now have Claude Code installed, verified, and anchored by persistent memory inside CLAUDE.md. By managing context with slash commands, tracking file diffs through git, and running test suites to validate code changes, you can guide autonomous coding sessions without unexpected drift or runaway token bills.
FAQ
Do I need an Anthropic Console API key to use Claude Code?
No. Claude Code supports browser-based authentication using an active Claude Pro or Max subscription as well as traditional Anthropic Console API keys.
Why is CLAUDE.md necessary if I can provide prompts directly?
Claude Code reads CLAUDE.md automatically at the start of tasks and retains those constraints even when context is compacted or cleared between commands.
How can I avoid excessive token spending in long sessions?
Check your consumption using /cost, compact your session history with /compact when tasks conclude, and use /clear before tackling unrelated features.