A practical tour of Claude Code from Source: the architecture, patterns and trade-offs behind a serious agentic CLI.
The repo is not Claude Code source. It is an independent educational reconstruction of the patterns that make an agentic coding tool useful, safe and fast.
Plain-English takeaway: the model is only one component. The durable advantage comes from the loop around it: tools, permissions, state, memory, concurrency, interfaces and recovery.
Trace a request from keystroke to model stream, tool call, permission decision and final output.
mental modelTake the transferable pieces: async generators, fail-closed tools, prompt-cache-aware forks and layered context compression.
architectureUse the how-to section as a sequence for building a safe, observable agent shell in your own stack.
practiceDesign an agent that can inspect a codebase, call tools, recover from errors, and keep a human in the loop when risk rises.
Evaluate architectures beyond model quality: where are the trust boundaries, cost controls, extension points and failure modes?
Turn “AI can code” into a usable workflow with observable progress, good terminal interaction and predictable stop conditions.
Study the system-level bets that determine agent behaviour in practice: memory selection, tool scheduling, and multi-agent coordination.
Boundary: the repository uses original pseudocode and analysis. Treat it as a pattern library, not as a drop-in clone or an authoritative description of Anthropic’s proprietary implementation.
Start with the shape of the system: the abstractions that make a language model into a working tool.
The interesting part isn’t the first model response. It’s what happens after the model asks to act.
Why an async generator? The consumer pulls messages at its own pace, which gives the loop natural backpressure, cancellation and typed terminal states.
A useful tool declares its input schema, output, concurrency safety, permission behaviour and progress surface.
Fail-closed defaults: new tools run serially and are treated as writes unless they explicitly prove they are safe to parallelise or read-only.
Built-in tools and MCP tools pass through the same validation, permission, result-budgeting and error-handling path. That consistency is the safety feature.
The full repo describes this as a 14-step pipeline. The four blocks above are the useful implementation boundaries.
A named permission mode gives you a system-level answer to “what can this agent do right now?”
| Mode | Behaviour | Good fit |
|---|---|---|
| plan | Read-only; deny mutations. | Discovery, architecture, impact analysis. |
| default | Prompt for unresolved operations. | Interactive developer workflow. |
| acceptEdits | Auto-allow file edits; prompt on other mutations. | Fast local iteration with a human boundary. |
| auto | Use a transcript-aware classifier for routine decisions. | Semi-autonomous, observable background work. |
| bubble | Escalate a child agent’s decision to its parent. | Coordinator / worker systems. |
| bypassPermissions | Allow everything without prompting. | Internal testing only. |
Design implication: the permission resolver should be a first-class subsystem with rules, provenance, hooks, user prompts and audit events, not a boolean tucked inside each tool.
Once the agent can act safely, performance and coordination become product features.
The loop protects the context window by applying the lightest intervention that solves the immediate pressure.
Product lesson: context pressure is user-visible latency and cost. Make compaction observable, reversible where possible, and tested against task continuity.
Start concurrency-safe tools while the model is still streaming. If the final call changes, discard the speculative result.
latency winWrites and context modifiers wait for the right point in the queue. This preserves causality and prevents conflicting side effects.
safety boundaryOne tool can be safe or unsafe depending on its input. ls and rm shouldn’t inherit the same concurrency classification merely because both arrive through Bash.
Give the child its own message history and deliberate visibility into the parent’s context.
Use bubble mode so dangerous requests travel back to a parent with a real user boundary.
Model resolution, hooks, skills, MCP, abort controllers, query loop and cleanup are explicit steps.
The strongest reusable idea is recursive sameness: a child agent should inherit the parent loop’s guarantees, while its context, tools and permissions are intentionally scoped.
Fork agents preserve a byte-identical prompt prefix, allowing multiple children to reuse the expensive shared context.
Freeze the parent’s rendered system prompt. Add a small fork marker. Let the child diverge only after the cached prefix.
The README describes a roughly 95% input-token saving for byte-identical fork prefixes. Treat this as the repo’s reported design claim, not a universal benchmark.
Trade-off: cache stability can constrain dynamic prompt content. A few unstable fields, headers or reordered tools can invalidate the benefit.
Project, user and team memories are stored as files, indexed with metadata, then selected for the current task. An always-loaded index can point to deeper memories.
Skills use two-phase loading: discover cheap frontmatter first, load full instructions only when invoked. Hooks intercept lifecycle events and can modify or block execution.
You don’t need 18 chapters to start. You do need the right order of operations.
Define messages and terminal states. Make cancellation, max turns, budget exhaustion and errors explicit.
Build one self-describing tool. Schema, execution, permission check, concurrency flag and result budget.
Put every call through one resolver. Hooks → rules → tool check → mode → prompt.
Add result budgeting and compaction. Protect the model from your own tool output.
Expose progress, costs and decisions. If the human can’t see the boundary, they can’t trust it.
Add memory, skills, MCP and child agents. Each should reuse the same loop and governance path.
async function *runAgent(input, deps) { let messages = [userMessage(input)] for (let turn = 0; turn < MAX_TURNS; turn++) { messages = compactIfNeeded(messages, deps.budget) const stream = yield* callModel(messages, deps.client) const calls = extractToolCalls(stream) if (calls.length === 0) return { kind: "completed" } const results = yield* executeTools(calls, deps) messages = messages.concat(results) } return { kind: "max_turns" } }
This is deliberately pseudocode. The repo’s examples are educational; your implementation should make its own contracts explicit.
type Tool<Input, Output> = { name: string inputSchema: Schema<Input> isReadOnly(input: Input): boolean isConcurrencySafe(input: Input): boolean checkPermissions(input: Input): Decision call(input: Input, ctx: ToolContext): Promise<ToolResult<Output>> } // safe defaults: serial + treated as a write const defaults = { isReadOnly: () => false, isConcurrencySafe: () => false }
ReadFile → ListFiles → Search → EditFile → RunCommand.
Use direct process calls for filesystem, shell and local project workflows. Keep permission and result contracts identical.
Wrap remote tools into the same model-facing interface. Handle transports, OAuth, timeouts, expiry and tool discovery.
Separate durable reads from HTTP writes, route messages, deduplicate echoes and make token refresh explicit.
Implementation rule: add connectivity by extending the adapter layer, not by teaching the core loop a new special case for every transport.
The repo’s highest-value contribution is not an exact implementation. It is a set of design questions you can ask of any agent architecture.
Model stream + file listing + file reading + search. No writes. Log every message and tool decision.
Add a diff-based edit tool, permission prompts, plan mode and result budgeting. Test denial paths first.
Add typed terminal states, retry boundaries, compact context and a small project-memory index.
Partition reads and writes. Speculate only on tools with a proven input-level safety classification.
Integrate one MCP server or one child agent through the same tool and permission path.
For any action, you can answer: what happened, why it was allowed, what it cost and how it can be stopped.
What is the loop? What can act? Who decides? What is remembered? What is parallel? What happens when the model is wrong?
The durable mental model: agent quality is the product of model capability, tool design, governance, context economics and interaction design.
Full book, web implementation and chapter navigation.
The project’s published interactive reading experience.
Five architectural bets, transfer boundaries and future directions.
Scope, table of contents and educational disclaimer.
Use ← → to navigate · O for overview · F for fullscreen