How Claude Code Works

---
name: how-claude-code-works
description: Deep dive into Claude Code internals — architecture, agent loop, context engineering, tool system, and security for building or understanding AI coding agents.
triggers:
  - how does claude code work internally
  - explain claude code architecture
  - how does the claude code agent loop work
  - claude code context engineering and compression
  - claude code tool system internals
  - how does claude code handle security and permissions
  - build my own ai coding agent like claude code
  - claude code hooks and extensibility
---

# How Claude Code Works

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

A 12-chapter deep dive into Claude Code's 500K+ line TypeScript source, covering architecture, the agent loop, context engineering, tool systems, permissions, multi-agent coordination, memory, skills, and UX design. Companion project to [`claude-code-from-scratch`](https://github.com/Windy3f3f3f3f/claude-code-from-scratch) — 1,300 lines, 8 chapters, build your own Claude Code.

## Reading the Docs

**Online:** https://windy3f3f3f3f.github.io/how-claude-code-works/#/

**Local:**
```bash
git clone https://github.com/Windy3f3f3f3f/how-claude-code-works
cd how-claude-code-works
# Open docs/ folder — plain Markdown, readable in any editor

Chapter map:

Key Architecture Concepts

System Architecture

User Input
    │
    ▼
QueryEngine (session management)
    │
    ▼
query() main loop ◄──────────────────────┐
    │                                     │
    ▼                                     │
Claude API (streaming)                    │
    │                                     │
    ├─► Text tokens → stream to terminal  │
    │                                     │
    └─► Tool calls → ToolExecutionEngine  │
              │                           │
              ├─ ReadFile                 │
              ├─ EditFile                 │
              ├─ Shell                    │
              ├─ Search                   │
              └─ MCP Tools               │
                      │                  │
                      └─ results ────────┘

Context Engineering layer feeds:
  - System prompt
  - Git status
  - CLAUDE.md files
  - Compression pipeline

The Agent Loop (docs/02-agent-loop.md)

Claude Code uses a dual-layer loop:

1. Outer loop — manages conversation state, compaction triggers, session lifecycle
2. Inner loop — single API call → parse response → execute tools → inject results → repeat

7 Continue Sites (fault recovery strategies):

• CONTINUE — normal tool result injection
• CONTINUE_WITH_COMPACTION — context too long, compress then continue
• CONTINUE_WITH_MAX_TOKENS_RETRY — upgrade 4K→64K output limit and retry
• STOP_WITH_RESULT — final answer reached
• STOP_WITH_ERROR — unrecoverable error
• STOP_WITH_INTERRUPT — user cancelled
• STOP_WITH_LIMIT — turn/cost limit hit

Tool pre-execution (StreamingToolExecutor): While the model streams its response, the system parses tool calls and begins executing them concurrently. The ~1s tool I/O latency is hidden inside the model's 5–30s generation window.

4-Level Context Compression (docs/03-context-engineering.md)

When context approaches the limit, compression triggers progressively:

Level 1: TRUNCATE
  └─ Cut large tool outputs in older messages (fast, lossy for old data)

Level 2: DEDUPLICATE  
  └─ Remove repeated content (near-zero cost)

Level 3: FOLD
  └─ Collapse inactive conversation segments (reversible, content intact)

Level 4: SUMMARIZE
  └─ Launch sub-agent to summarize entire conversation (last resort)

After any compression, the system auto-restores:

• The 5 most recently edited files (full content re-injected)
• Active skill context (prevents the model forgetting what it was doing)

Tool System (docs/04-tool-system.md)

All 66+ tools share one interface:

interface Tool {
  name: string;
  description: string;
  inputSchema: ZodSchema;
  execute(input: unknown, context: ToolContext): Promise<ToolResult>;
  readonly: boolean;        // true = can run in parallel
  requiresPermission: boolean;
}

Concurrency rules (automatic):

• Read-only tools → parallel execution
• Write tools → serialized automatically
• Output > 100K chars → written to disk, model receives path + summary

5-Layer Permission System (docs/10-permission-security.md)

Layer 1: Permission Mode
  └─ Trust level restricts available operation classes

Layer 2: Rule Matching
  └─ Command pattern whitelist/blacklist

Layer 3: Bash AST Analysis (tree-sitter)
  └─ 23 safety checks on parsed shell AST, not regex:
     - Command injection detection
     - Env variable leak detection  
     - Special character attacks
     - Pipe chain analysis

Layer 4: User Confirmation
  └─ Dangerous ops require explicit confirm
     200ms debounce prevents accidental keypress confirmation

Layer 5: Hook Validation
  └─ User-defined rules, can mutate tool inputs
     (e.g. auto-add --dry-run to rm commands)

Hooks System (docs/06-hooks-extensibility.md)

Configure in .claude/hooks.json or CLAUDE.md:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "my-safety-checker --input-file $CLAUDE_TOOL_INPUT"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command", 
            "command": "prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

23+ hook events including:

• PreToolUse / PostToolUse — intercept any tool call
• PreBashCommand — inspect shell commands before execution
• OnError — custom error handling
• OnSessionStart / OnSessionEnd
• OnContextCompaction — triggered before compression

Hook can return PermissionRequest with 4 capabilities:

1. APPROVE — bypass normal permission check
2. DENY — block the operation
3. MODIFY_INPUT — mutate the tool's input parameters
4. PROVIDE_REASON — add explanation shown to user

Multi-Agent Architecture (docs/07-multi-agent.md)

3 coordination modes:

Sub-Agent:
  Main Agent ──dispatch──► Sub Agent
                              │
                              └─ executes task
                              └─ returns result ──► Main Agent continues

Coordinator (pure orchestration):
  Coordinator ──task──► Agent A (reads files, writes code)
  Coordinator ──task──► Agent B (runs tests)
  Coordinator CANNOT read/write itself — enforces separation

Swarm (peer-to-peer):
  Agent "Alice" ◄──mailbox──► Agent "Bob"
  Agent "Bob"   ◄──mailbox──► Agent "Carol"
  Each agent independent, 3 execution backends

Worktree isolation: Each agent gets its own Git worktree copy to prevent concurrent file edit conflicts.

Memory System (docs/08-memory-system.md)

4 memory types:

1. In-context — current conversation window
2. External files — CLAUDE.md, project docs injected at session start
3. Semantic memory — Sonnet-based recall with async prefetch
4. Background extraction — sub-agent runs after sessions to extract learnings

Anti-drift: Memory entries use a closed taxonomy (structured tags) to prevent semantic drift over many sessions.

Code Editing Strategy (docs/05-code-editing-strategy.md)

Claude Code uses search-and-replace over whole-file rewrite:

Why search-and-replace:
  ✓ Smaller diffs → fewer tokens → lower cost
  ✓ Uniqueness constraint forces model to be precise
  ✓ Hallucination resistance (must match exact existing text)
  ✓ Preserves unchanged code exactly (no reformatting side effects)

Uniqueness constraint:
  The search string must appear EXACTLY ONCE in the file.
  If 0 matches → error, model must retry with more context.
  If 2+ matches → error, model must add surrounding lines.

Pre-edit read enforcement:
  Tool executor checks whether the file was read in current context.
  If not → forces a ReadFile call first, then allows edit.

Building Your Own Agent (Minimal Components)

From docs/12-minimal-components.md — the 7 minimal components:

// 1. Message loop
async function agentLoop(userMessage: string) {
  messages.push({ role: 'user', content: userMessage });
  
  while (true) {
    const response = await anthropic.messages.create({
      model: 'claude-opus-4-5',
      messages,
      tools: toolDefinitions,
      stream: true,
    });
    
    // 2. Stream handler
    for await (const chunk of response) {
      if (chunk.type === 'content_block_delta') {
        process.stdout.write(chunk.delta.text ?? '');
      }
    }
    
    // 3. Tool execution
    const toolUses = extractToolUses(response);
    if (toolUses.length === 0) break;  // done
    
    const results = await Promise.all(
      toolUses.map(t => executeTool(t.name, t.input))
    );
    
    // 4. Result injection
    messages.push({ role: 'assistant', content: response.content });
    messages.push({ role: 'user', content: results.map(toToolResult) });
  }
}

// 5. Tool registry
const tools = new Map<string, ToolHandler>();
tools.set('read_file', async ({ path }) => fs.readFile(path, 'utf8'));
tools.set('write_file', async ({ path, content }) => fs.writeFile(path, content));
tools.set('bash', async ({ command }) => execSync(command, { encoding: 'utf8' }));

// 6. Context management (basic)
function trimContext(messages: Message[], maxTokens: number) {
  // Estimate tokens, drop oldest non-system messages until within budget
  while (estimateTokens(messages) > maxTokens) {
    const firstNonSystem = messages.findIndex(m => m.role !== 'system');
    if (firstNonSystem === -1) break;
    messages.splice(firstNonSystem, 1);
  }
}

// 7. Permission check (minimal)
async function checkPermission(tool: string, input: unknown): Promise<boolean> {
  const dangerous = ['bash', 'write_file', 'delete_file'];
  if (!dangerous.includes(tool)) return true;
  const answer = await prompt(`Allow ${tool}? [y/N] `);
  return answer.toLowerCase() === 'y';
}

Full 1,300-line implementation: https://github.com/Windy3f3f3f3f/claude-code-from-scratch

Performance Design Patterns

9-Phase Parallel Startup (~235ms critical path)

Phase 1-3 (parallel): Load config + Init MCP + Check git status
Phase 4-6 (parallel): Load CLAUDE.md + Prefetch memory + Warm tool registry  
Phase 7-8 (parallel): Init renderer + Authenticate
Phase 9 (sequential): Start agent loop

Streaming Pipeline

API chunk arrives
      │
      ▼ (< 1ms)
Token renderer (Ink + Yoga Flexbox)
      │
      ▼
Terminal output
      │
      ├─ Meanwhile: parse partial JSON for tool calls
      └─ Tool pre-execution starts before stream ends

Prompt Cache Strategy

Claude Code structures its system prompt for maximum cache hits:

[CACHED - rarely changes]
  System prompt core
  Tool definitions (all 66)
  CLAUDE.md content

[NOT CACHED - changes every turn]  
  Git status
  Current file contents
  Recent tool results
  User message

Cache break detection: If cache hit rate drops below threshold, system re-orders content blocks to restore caching.

Common Patterns for AI Agent Development

Reliable File Editing

// Always read before edit — Claude Code enforces this at the executor level
async function safeEdit(path: string, search: string, replace: string) {
  const content = await fs.readFile(path, 'utf8');
  
  const matches = content.split(search).length - 1;
  if (matches === 0) throw new Error(`Search string not found in ${path}`);
  if (matches > 1) throw new Error(`Search string ambiguous (${matches} matches) — add more context`);
  
  return content.replace(search, replace);
}

Context Window Management

const COMPRESSION_THRESHOLDS = {
  TRUNCATE: 0.80,      // 80% full → truncate old tool outputs
  DEDUPLICATE: 0.85,   // 85% → deduplicate  
  FOLD: 0.90,          // 90% → fold inactive segments
  SUMMARIZE: 0.95,     // 95% → summarize entire history
};

async function manageContext(messages: Message[], tokenCount: number, maxTokens: number) {
  const ratio = tokenCount / maxTokens;
  
  if (ratio > COMPRESSION_THRESHOLDS.SUMMARIZE) {
    return await summarizeHistory(messages);  // sub-agent summarizes
  } else if (ratio > COMPRESSION_THRESHOLDS.FOLD) {
    return foldInactiveSegments(messages);
  } else if (ratio > COMPRESSION_THRESHOLDS.DEDUPLICATE) {
    return deduplicateMessages(messages);
  } else if (ratio > COMPRESSION_THRESHOLDS.TRUNCATE) {
    return truncateToolOutputs(messages);
  }
  return messages;
}

Shell Safety (simplified from the 23-check AST analyzer)

const DANGEROUS_PATTERNS = [
  /rm\s+-rf?\s+\/(?!\w)/,    // rm -rf /
  />\s*\/dev\/sd[a-z]/,      // write to block device
  /chmod\s+777/,              // world-writable
  /curl.*\|\s*bash/,          // curl pipe bash
  /eval\s*\(/,                // eval injection
];

function isSafeCommand(command: string): boolean {
  return !DANGEROUS_PATTERNS.some(p => p.test(command));
}

Troubleshooting Common Agent Issues

Key Metrics from Source Analysis

Related Resources

• Source analysis docs: https://windy3f3f3f3f.github.io/how-claude-code-works/#/
• Build from scratch (1,300 lines, 8 chapters): https://github.com/Windy3f3f3f3f/claude-code-from-scratch
• Official Claude Code: https://github.com/anthropics/claude-code
• Anthropic API docs: https://docs.anthropic.com