Claude Code Architecture

High-Level Architecture

Claude Code is a terminal-based agentic coding assistant. At its core, it's a loop: send messages to the Claude API, receive tool calls, execute them with permission checks and hooks, feed results back, and repeat.

The entire system is built as async generators — each layer yields messages upstream for the UI to render in real-time. This is what makes tool progress, streaming text, and hook feedback all appear incrementally.

The Query Loop query.ts

The heart of Claude Code. queryLoop() is a while(true) loop that handles message preparation, API calls, tool execution, and error recovery across turns.

Each Iteration

Streaming & Fallback

The API call uses a generator (callModel()) that yields StreamEvent messages as they arrive from the Anthropic API. Text, thinking blocks, and tool_use blocks arrive incrementally.

Streaming Tool Executor

While the model is still generating, tool_use blocks that have completed streaming are immediately dispatched for execution via the StreamingToolExecutor. This means tools can finish before the model even stops generating.

// While model still streams, start executing completed tool_use blocks
if (streamingToolExecutor) {
  streamingToolExecutor.addTool(toolUseBlock)       // Feed in as they arrive
  yield* streamingToolExecutor.drainResults()     // Yield completed results
}

Fallback Model

If the primary model throws a FallbackTriggeredError (overloaded, rate limited), the loop catches it, clears partial state, switches to the fallback model, and retries from the same point. Thinking blocks are stripped from the retry to avoid signature mismatches between models.

Compaction Pipeline 5 Layers

Before each API call, the conversation is compressed through up to 5 stages to stay within context limits:

Error Recovery

The query loop has multiple recovery strategies that fire in escalating order:

Tool Architecture Tool.ts

Every tool is built with buildTool() which applies fail-closed defaults:

Tool Capabilities

Tool Execution Lifecycle toolExecution.ts

Every tool call follows this exact sequence:

runToolUse(toolUseBlock)
  // 1. Find tool by name (with deprecated alias fallback)
  // 2. Validate input against Zod schema
  // 3. Run PreToolUse hooks
  → executePreToolHooks(toolName, input)
      // Hooks can: approve, deny, modify input, inject context

  // 4. Check permissions
  → resolveHookPermissionDecision()
      // Combines hook decision + canUseTool() + rule-based checks
      // Priority: deny > ask > allow > passthrough

  // 5. Execute tool
  → tool.call(validatedInput, context)
      // Returns: { data, newMessages?, success }

  // 6. Run PostToolUse hooks
  → runPostToolUseHooks(toolName, input, output)
      // Hooks can: modify MCP output, inject context, stop continuation

  // 7. On error: run PostToolUseFailure hooks instead

Concurrency Model toolOrchestration.ts

When the model returns multiple tool_use blocks, they're partitioned into batches:

partitionToolCalls([Read, Read, Edit, Grep, Bash])
  → Batch 1: [Read, Read]         // concurrent (both read-only)
  → Batch 2: [Edit]               // serial (writes)
  → Batch 3: [Grep]               // concurrent (read-only)
  → Batch 4: [Bash]               // serial (not concurrency-safe)

Concurrent batches run up to 10 tools in parallel. Context modifiers from concurrent tools are queued and applied after the batch completes. Serial tools apply context modifiers immediately.

Streaming Tool Executor

The most interesting optimization: tools start executing while the model is still generating.

Hooks System 5,000+ lines

The hooks system is the extensibility layer of the harness. There are 25+ hook events across the entire lifecycle:

Hook Configuration

Hooks are configured in settings.json at user, project, or policy level:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "my-lint-check.sh",
            "if": "Bash(npm *)",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Four Hook Types

Matchers & Conditions

Each hook entry has a matcher (which tool to match) and optional if condition:

• "matcher": "Write" — exact match on tool name
• "matcher": "Write|Edit" — pipe-separated alternatives
• "matcher": "^Write.*" — regex match
• "matcher": "*" — matches all tools
• "if": "Bash(git *)" — permission rule syntax, filters before spawning

stdin/stdout Protocol Command Hooks

Command hooks communicate via JSON over stdin/stdout. Here's the exact protocol:

Input (stdin)

{
  "session_id": "uuid",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/working/directory",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "git status" },
  "tool_use_id": "toolu_abc123"
}

Output (stdout)

{
  "decision": "approve",               // or "block"
  "reason": "Looks safe",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",     // "allow" | "deny" | "ask"
    "updatedInput": { "command": "git status --short" },
    "additionalContext": "Reminder: this repo uses trunk-based development"
  }
}

Async Detection

A hook can background itself by emitting this as its first line of stdout:

{ "async": true, "asyncTimeout": 5000 }

The harness immediately returns an empty result and the hook continues running in the AsyncHookRegistry. If asyncRewake is set and the hook exits with code 2, it re-wakes the model with its output.

Exit Code Semantics

Permission System 5 Rule Sources

Every tool invocation passes through a multi-layer permission check:

Permission Behaviors

• allow — tool runs without prompting
• deny — tool is blocked, model sees denial message
• ask — user is prompted interactively

Rule Syntax

// Allow all git commands
{ "tool": "Bash(git *)", "permission": "allow" }

// Deny writes to node_modules
{ "tool": "Write(node_modules/**)", "permission": "deny" }

// Ask before any destructive bash command
{ "tool": "Bash(rm *)", "permission": "ask" }

Rules use bash-style glob patterns. Tools implement preparePermissionMatcher() to normalize their input for pattern matching (e.g., FileEditTool matches against file paths, BashTool matches against commands).

Speculative Classifiers

In auto-mode, two classifiers run speculatively in the background while the permission prompt is shown to the user:

Both are gated by feature flags (BASH_CLASSIFIER, TRANSCRIPT_CLASSIFIER). There's also denial tracking — after N auto-denials, the system falls back to interactive prompting.

System Prompt Assembly

The system prompt is built from a 5-level priority stack:

appendSystemPrompt is always added at the end (unless override is set).

Default Prompt Sections

The default system prompt is assembled from these sections in prompts.ts:

1. Intro (model description, safety instructions)
2. System section (tool execution, tags, compression)
3. Doing tasks section (task approach guidance)
4. Actions section (reversibility, blast radius)
5. Using your tools section (tool-specific instructions)
6. Tone and style section
7. Output efficiency section
8. — DYNAMIC BOUNDARY —
9. Session guidance, memory, environment info, language, output style, MCP instructions...

Cache Boundary Critical Optimization

The system prompt is split at __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__:

Section Caching

Dynamic sections use two caching strategies:

• systemPromptSection() — computed once, cached until /clear or /compact
• DANGEROUS_uncachedSystemPromptSection() — recomputed every turn, breaks prompt cache on changes. Used for MCP instructions (servers connect/disconnect between turns)

Context Injection

Two context objects are injected alongside the system prompt:

System Context

• Git status — branch, main branch, status (max 2,000 chars), recent commits, git user
• Cache breaker — ANT-only ephemeral injection for debugging

User Context

• CLAUDE.md files — auto-discovered via directory walk, filtered to remove injected memory files
• Current date — always included

System context is prepended, user context is appended. Both are memoized at module load and cached for the session.

Memory System memdir/

Persistent memory stored in ~/.claude/projects/<slug>/memory/:

Three Memory Modes

Sub-Agent System AgentTool

The AgentTool spawns isolated sub-agents that run their own query loops with restricted tool sets.

Agent Properties

• Each agent gets a subagent_type, custom system prompt, and tool restrictions
• Optional isolation: "worktree" for git worktree isolation
• Auto-backgrounds after 120 seconds (GrowthBook-gated)
• Background tasks disabled globally via CLAUDE_CODE_DISABLE_BACKGROUND_TASKS
• Results arrive as <task-notification> XML blocks

Fork Subagent FORK_SUBAGENT gate

The most sophisticated agent pattern. When enabled, omitting subagent_type triggers an implicit fork of the current agent.

Cache Optimization

Fork children receive the parent's exact system prompt bytes to preserve prompt cache identity. The fork message contains:

• The entire parent assistant message (all tool_use blocks, thinking, text)
• Identical placeholder tool results for all sibling forks: "Fork started — processing in background"
• Only the final text block differs per child (the directive)

This maximizes cache hits across siblings — the messages are identical until the final divergence point.

Fork Child Rules

1. You ARE a fork — don't spawn sub-agents
2. No conversation; use tools directly
3. Commit changes before reporting (include hash)
4. Minimal output: "Scope:", "Result:", "Key files:" format

Coordinator Mode

Gate: COORDINATOR_MODE + CLAUDE_CODE_COORDINATOR_MODE env var.

A single coordinator spawns multiple worker agents via the Agent tool. Workers run as background agents with restricted tool sets:

Workers can share knowledge via a scratchpad directory (gated by tengu_scratch). The coordinator waits for actual results — no prediction.

Swarm Infrastructure

Full multi-process agent orchestration with multiple terminal backends:

Permission bubbling: teammate agents can escalate permission requests up to the leader. Team files managed via teamHelpers.ts with task numbering.

Feature Flags ~50+ gates

Bun's feature() function enables build-time dead code elimination. Disabled features are completely stripped from the binary.

ANT-Only Code

process.env.USER_TYPE === 'ant' is a build-time constant. Ant-only features are DCE'd from external builds:

• Remote isolation mode for agents
• agents-platform command
• Internal telemetry, cache breaking injection
• Numeric length anchors (token reduction hints)
• Model codename references

Speculative Execution Hidden Feature

Claude Code can speculatively execute the next task in the background before you even ask.

How It Works

1. After completing a turn, a forked agent runs in an isolated overlay directory
2. The overlay allows write tools (Edit, Write) to modify copies of files
3. Read-only tools (Read, Glob, Grep) access the real filesystem
4. Max 20 turns, 100 messages per speculation
5. If the user accepts the suggestion, overlay files are copied to the real working directory
6. If rejected, the overlay is discarded

Undercover Mode ANT-Only

When Anthropic engineers use Claude Code on public repos, this auto-activates:

• Strips model codenames (Tengu, Capybara, etc.) from commits and PRs
• Strips internal repo names and Slack references
• External repos are default — only an internal allowlist turns it off
• No force-off — safety guarantee that codenames never leak
• Controlled via CLAUDE_CODE_UNDERCOVER=1 or auto-detection

Cost Tracking cost-tracker.ts

Token usage and costs are tracked per-session and persisted across resumes:

• Input, output, cache read, cache write tokens tracked per model
• API duration, tool duration, wall duration tracked
• Lines of code changed tracked
• FPS metrics (terminal rendering performance) optionally captured
• Advisor tool usage tracked recursively
• Persisted to project config on session switch, restored on resume

Limits & Constants

Trust Gate

All hooks require workspace trust in interactive mode. This is a defense-in-depth measure:

function shouldSkipHookDueToTrust(): boolean {
  const isInteractive = !getIsNonInteractiveSession()
  if (!isInteractive) return false  // SDK mode: trust implicit
  const hasTrust = checkHasTrustDialogAccepted()
  return !hasTrust  // Interactive: all hooks require trust
}

This prevents a malicious .claude/settings.json in a cloned repo from executing arbitrary commands before the user accepts the trust dialog. Applied to ALL hook types with no exceptions.