Visual reference for Claude Code internals — architecture, MCP ecosystem, multi-agent patterns, security models, and development workflows. 38 SVGs rendered at build time, zero client JavaScript.
Core concepts: 4-layer model, workflow pipeline, decision tree, 5 permission modes
Claude Code isn't a chatbot — it's a context system that transforms your message into a rich multi-layer prompt before calling the API. This diagram shows the 4-layer augmentation that happens invisibly with every request.
How Claude Code Works — Line ~2360
Every request to Claude Code goes through this pipeline — from parsing your intent to displaying the final response. Understanding this loop helps you write better instructions and diagnose issues faster.
Getting Started — Line ~277
Not every task needs Claude Code. This decision tree helps you route the right tasks to the right tool — Claude Code CLI vs Claude.ai vs clipboard-based approaches.
Quick Start Decision — See also `machine-readable/reference.yaml` (decide section)
Claude Code has 5 permission modes that control what it can do automatically vs. what requires your approval. Choosing the wrong mode is the #1 safety mistake.
Permission System — Line ~760
Context zones, memory hierarchy, session management, and fresh context patterns
Your context window has 4 distinct zones, each requiring different strategies. Knowing which zone you're in prevents context bloat and maintains response quality throughout long sessions.
Context Management — Line ~1335
Claude Code has 6 distinct memory types with different scopes and persistence. Knowing which memory type to use for each piece of information is key to effective sessions.
Memory System — Line ~3160 & ~3986 | Auto-Memory: v2.1.59+ (v3.30.0)
Sessions don't automatically persist context between terminals. This diagram shows how to save state and resume it in a new session or terminal, enabling async workflows.
Session Management — Line ~9477
Long sessions accumulate noise that degrades response quality. This diagram shows the degradation pattern and the recommended "focused sessions" approach that maintains performance.
Context Best Practices — Line ~1525
Config precedence, skills vs commands vs agents, agent lifecycle, hooks pipeline
Claude Code resolves settings through a strict priority hierarchy. Higher layers override lower ones. Knowing this prevents "why isn't my config working?" bugs.
Configuration System — Line ~3760
Three extensibility mechanisms with different purposes and tradeoffs. Choosing the wrong abstraction leads to over-engineering or under-powered automation.
Extensibility System — Line ~4495, ~5025, ~3900
Sub-agents run in complete isolation from the parent. They receive a copy of context but share no state. Understanding this prevents "why can't my sub-agent see X?" confusion.
Sub-Agents — Line ~3900
Hooks let you run custom code at key points in Claude Code's lifecycle — for security scanning, logging, enforcement, or notifications. The execution order matters.
Session starts
│ (InstructionsLoaded Hook — v2.1.69+)
User message
│
UserPromptSubmit ──exit 2──► feedback to Claude (loop)
│ exit 0
PreToolUse ──exit 1──► BLOCKED
│ exit 0
▼
Tool executes
│
PostToolUse
│
More tools? ──yes──► PreToolUse (loop)
│ no
Session ends
│
Stop / SessionEnd Hook
│
Complete
Separately: PreCompact ──► /compact ──► PostCompact
Hook types: bash (exit 0/1/2) | http POST JSON (v2.1.63+) Hooks System — Line ~5350 | UserPromptSubmit + HTTP hooks: v2.1.63+ | InstructionsLoaded: v2.1.69+
Master loop, tool categories, system prompt assembly, sub-agent isolation
Claude Code's core execution is two nested loops: an **inner agent loop** that keeps calling the API as long as tool calls are returned, and an **outer conversation loop** that starts a new turn when the user responds.
Architecture: Master Loop — Line ~72
Claude Code has 6 tool categories, each optimized for different operations. Understanding which tool Claude chooses (and why) helps you write instructions that guide better tool selection.
Architecture: Tools — Line ~213
Before every API call, Claude Code assembles a system prompt from multiple sources in a specific order. The prompt is split into two cache zones separated by a boundary marker.
Architecture: System Prompt — Line ~354
Sub-agents are completely isolated from the parent — they can't read the parent's conversation or modify parent state. This isolation is a feature (safety) and a constraint (intentional design).
Architecture: Sub-Agents — Line ~444
MCP server map, architecture, rug pull attack chain, config hierarchy
The MCP ecosystem has 4 categories of servers — official, community-dev, community-ops, and local. Knowing what's available prevents building what already exists.
MCP Ecosystem — Full guide
MCP is a JSON-RPC protocol running over stdio or SSE. Claude Code acts as the client, MCP servers as tool providers. This shows the full request-response cycle.
Architecture: MCP — Line ~795
The most dangerous MCP attack vector: malicious tool descriptions containing hidden prompt injection. This is why you should only install vetted MCP servers.
Security: MCP Threats — Line ~33
MCP server configurations can live in 4 priority levels (3 actual files). The resolution order determines which servers are available and who can override what.
MCP Configuration — Line ~6149
TDD cycle, spec-first pipeline, plan-driven workflow, iterative refinement loop
Test-Driven Development adapted for Claude Code: write the failing test first, then ask Claude to implement only what's needed to pass it. This prevents over-engineering and ensures tests actually verify behavior.
TDD with Claude
Write the specification before the code. Claude uses the spec as the single source of truth — preventing drift between what was planned and what was built.
Spec-First Development
Complex tasks benefit from plan mode: Claude explores the codebase, proposes a plan, you annotate it, then Claude executes only what was approved. Prevents surprises on large refactors.
Plan-Driven Workflow
Output rarely hits the mark on the first try. This loop gives you a systematic way to improve results through targeted feedback rather than "make it better" vague instructions.
Iterative Refinement — Line ~347
When Claude produces a polished-looking output, a cognitive bias kicks in: the more complete the output appears, the less critically most users evaluate it. This is the Artifact Paradox, documented by Anthropic across 9,830 conversations. The diagram shows what separates the 30% of high-fluency users from the 70% who accept first outputs — and the measurable difference in outcome quality.