aradotso/trending-skills/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:**

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:**
 
| File | Topic |
|------|-------|
| `docs/quick-start.md` | 10-minute condensed overview |
| `docs/01-overview.md` | Tech choices, 9-phase startup, data flow |
| `docs/02-agent-loop.md` | Dual-layer loop, 7 Continue Sites, streaming tool execution |
| `docs/03-context-engineering.md` | 4-level compression pipeline, cache strategy |
| `docs/04-tool-system.md` | 66 tools, MCP, concurrency, OAuth |
| `docs/05-code-editing-strategy.md` | search-and-replace, uniqueness constraint |
| `docs/06-hooks-extensibility.md` | 23+ hook events, 6-stage pipeline |
| `docs/07-multi-agent.md` | Sub-agents, coordinator, Swarm, Worktree isolation |
| `docs/08-memory-system.md` | 4 memory types, semantic recall, drift defense |
| `docs/09-skills-system.md` | 6-layer skill sources, lazy load, token budget |
| `docs/10-permission-security.md` | 5-layer defense, AST analysis, 23 safety checks |
| `docs/11-user-experience.md` | Ink renderer, Yoga Flexbox, virtual scroll |
| `docs/12-minimal-components.md` | Minimal viable agent, 500→500K line roadmap |
 
---
 
## 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