How Claude Code Works

A coding agent is a text model wrapped in a loop that runs its tool requests and feeds back the results; every feature is a layer around that loop.

The harness and the loop

• Agentic harness: the tools, context management, and execution environment that turn a model into an agent. Claude Code is the harness; Claude is the model inside it.
• Model only reads text and writes text. It cannot open files, run tests, or click. The harness executes every action.
• Agentic loop (four beats): gather context, take action, verify results, repeat until done.
• Mechanically it is a while loop around one API call, driven by stop_reason: tool_use means act; anything else exits with final text.
• Tool call = a contract, not a function: tool definition (in) → tool_use block (model picks tool + args) → tool_result (returned), matched by tool_use_id. The harness sits between model and action, so memory, permissions, hooks, and verification all intervene there.

gather context → model decides → [tool_use] → harness runs tool → append tool_result → (loop)
                              → [no tool]   → turn ends

Context, memory, caching

• Window holds: system instructions, CLAUDE.md + auto memory, loaded skills, conversation history + tool results, file/command output.
• Output style modifies the system prompt (appended); changes how Claude responds, read once at session start, needs a new session.
• CLAUDE.md is injected as a user message after the system prompt; re-applied, survives compaction, refreshable mid-session. All files concatenated broadest→most-specific.
• Compaction: drops oldest tool outputs first (cheap), then summarizes older history (lossy). Trigger with /compact, inspect with /context. Keep anything you truly need in a file or CLAUDE.md, not scrollback.

Prompt-cache economics

• Rates relative to base input: 5-min cache write 1.25x, 1-hour cache write 2x, cache read 0.1x (a tenth of fresh input).
• Cache lifetime: 1 hour on subscription, 5 min on API keys / usage credits.
• Break-even: 1 cache read (5-min tier), 2 reads (1-hour tier).
• Cost is dominated by how much stable context stays warm in cache, not by your last message length.

Thinking and effort

• Thinking tokens are billed as output tokens.
• Effort level low→max (default high) trades reasoning spend for capability.
• Gotcha: on some models low effort uses fewer total tokens than thinking off, because fewer mistakes mean fewer retries.

Four surfaces that bend the loop

• Hooks: your code run at fixed lifecycle events (UserPromptSubmit, PreToolUse, PostToolUse, Stop, session start/end). Subprocess contract: tool call sent as JSON on stdin; exit 2 blocks, or return JSON permissionDecision (allow/deny/prompt). Deterministic, can block. Common use: trim test logs to FAIL lines before Claude sees them.
• Skills: folder with SKILL.md. Progressive disclosure, 3 levels — L1 name+description always in context; L2 body loaded when invoked; L3 bundled files/scripts on demand (scripts run without loading their text). Custom slash commands are now merged into skills.
• Plan mode: read/search/explore, edits blocked until you approve a written plan. Cycle with Shift+Tab.
• Permissions: three arrays deny, ask, allow, evaluated in that order, first match wins; no match → prompt. Scalars override by precedence, but permission arrays merge across layers (a user deny still applies in a project).

Orchestration, remotes, sandbox

• Subagent: verbose work runs in its own context window; only a summary returns to main. Same idea as compaction, applied preemptively.
• Three “remote” mechanisms — question that separates them: on which machine is the model’s loop running?

• claude --teleport <id> pulls a cloud session into your terminal (checks repo, checks out cloud branch, loads history).
• Sandbox: bubblewrap (Linux), Seatbelt/sandbox-exec (macOS). Filesystem confined to cwd; network forced through a domain-validating proxy. Reduces permission prompts by 84%.
• Credentials (git, signing keys) are held outside the sandbox; auth via proxy with scoped short-lived creds, so a compromised agent can’t read secrets. Defense against prompt injection.

Verification closes the loop

• Claude stops when work looks done. Without a runnable check, you become the verification loop.
• A check = anything returning pass/fail: test suite, build exit code, linter, fixture diff, or a browser screenshot vs design. It re-enters the loop as another tool_result (ground truth).
• Pattern is evaluator-optimizer: one call generates, another evaluates in a loop; fits when evaluation criteria are clear.
• Four escalating enforcements (soft→deterministic): in-prompt “run tests and iterate” → /goal re-checks each turn → Stop hook blocks until check passes → review subagent (fresh model tries to refute). Strongest is the independent verifier — the worker shouldn’t grade its own homework.

Screenshots: two mechanisms

• Computer-use API tool: drives a full desktop, loop = screenshot/act/screenshot. Claude doesn’t connect directly; your app captures, clicks, returns the new screenshot as tool_result. Outputs pixel coordinates, sandboxed virtual display. Prompt it to screenshot and verify after each step (it otherwise assumes outcomes).
• Claude Code UI verification: a browser workflow (Chrome integration — reads console errors, DOM, captures screenshots). Paste a design, build, screenshot, compare, fix.
• Both close the same build/look/compare/fix loop; a screenshot is just another tool_result.