Claude Code From Scratch offers a rare, hands-on look at the architecture behind Anthropic’s Claude Code, distilled into manageable, incremental Python sessions. Its core idea flips the usual AI agent setup: instead of the harness deciding what to do, the model is the only decision-maker, issuing strictly typed tool calls that the harness executes without interpretation or branching. This approach, dubbed “harness engineering,” creates a reliable and extensible system that’s worth understanding for anyone building advanced AI coding assistants.
The architecture behind Claude Code From Scratch
This repository reverse-engineers Claude Code’s complex architecture through 23 progressive Python sessions. Each session adds exactly one new mechanism, starting from a minimal perception-action loop and culminating in a production-level system. Key features include streaming token loops, permission governance via YAML, context compaction pipelines, isolated subagent contexts, parallel tool execution, and autonomous agent teams communicating through JSONL mailboxes.
At the heart is a minimal perception-action loop: the model perceives input and decides the next action in a continuous cycle. The harness never branches on model output; instead, it uses a typed tool dispatch map to execute commands. This means the model outputs structured, schema-validated tool calls rather than freeform text or code that the harness must heuristically interpret. This design enforces a clear separation of concerns — the model decides and the harness executes — improving reliability and safety.
All sessions import from a single core.py file (~392 lines), which implements the core loop and dispatch mechanics. This consolidation makes the architecture learnable and reproducible, allowing developers to incrementally add features without losing sight of the core design.
Context management is handled as a curated, compressible resource across sessions. The system employs a four-layer context compaction pipeline to handle token limits imposed by large language models, distilling information while preserving relevance. This is critical for maintaining continuity over long interactions and large codebases.
Permission governance is declarative and enforced upfront using YAML configurations. This prevents unauthorized tool usage and ensures the harness respects security boundaries.
The system also supports subagent context isolation and parallel tool execution, enabling sophisticated multi-agent workflows. Autonomous agent teams communicate through JSONL mailboxes, coordinating complex tasks asynchronously.
Importantly, the harness is agnostic to the LLM provider. It uses a LiteLLM proxy layer that lets you plug in any supported large language model without changing the harness code.
The distinguishing technical aspects and tradeoffs
What sets this project apart is the harness engineering philosophy. Many AI agents mix decision-making and execution in messy ways, interpreting freeform model output and guessing intent. Here, the model outputs strictly typed tool calls validated by JSON schemas. This means the harness can be minimal, predictable, and safe — it does not parse or branch on model output but simply follows a typed interface.
This design reduces surface area for errors caused by ambiguous or unexpected model outputs. It also makes it easier to audit and extend the system because every action is explicit and validated.
The incremental session-based approach is another strength. By adding one mechanism at a time, the repo teaches the architecture in digestible steps without overwhelming complexity. It’s a great learning resource for those aiming to build robust AI coding assistants.
The 392-line core.py acts as the single source of truth, simplifying maintenance and understanding. The harness’s approach to context as a compressible resource addresses a real pain point in LLM applications — handling limited token budgets while preserving relevant information.
The tradeoff is a more rigid harness that depends on the model strictly adhering to the tool call schema. If the model deviates or misunderstands, the harness has less flexibility to recover. Also, the layered context compaction adds complexity and may lose some nuance in compressed contexts.
Permission governance through YAML is straightforward and declarative but requires careful configuration to avoid overly permissive or restrictive rules.
Overall, the code quality looks clean and focused on clarity and reproducibility rather than bells and whistles. The repo is primarily educational, so it’s not a plug-and-play production system but a solid base for experimentation and extension.
Explore the project
The repo is structured as 23 Python sessions, each building on the previous one. The main entry point for understanding the core mechanics is core.py, which implements the perception-action loop and tool dispatch.
Documentation is embedded in the README and comments throughout the code, explaining each new mechanism introduced in the sessions.
Key resources include:
- The
core.pyfile for the harness loop and tool dispatch - YAML files defining permission governance
- The folder structure organizing sessions incrementally
- LiteLLM proxy implementation for LLM provider abstraction
Start by browsing the early sessions to see how the minimal loop works, then move forward to explore context compaction, subagents, streaming, and multi-agent coordination.
Since the harness enforces typed interfaces using JSON schemas, reviewing the tool definitions and schema validations provides insight into how the model-to-harness contract is maintained.
Verdict
Claude Code From Scratch is a valuable resource for developers building AI coding assistants who want a clear, principled architecture that separates decision-making from execution. Its harness engineering approach enforces reliability and safety through typed interfaces and declarative permissions.
The incremental session design makes the repo approachable as a learning tool, though it’s not an out-of-the-box production system. It demands adherence to strict schemas and disciplined context management, which may be restrictive but pays off in predictable behavior.
This repo is relevant for AI researchers, developers working on LLM agents, and anyone interested in the engineering challenges of building robust AI assistants. It’s less suitable for those seeking quick plug-and-play solutions or who prefer more flexible, heuristic-driven agent designs.
The harness engineering philosophy — the model as sole decision-maker, the harness as strict executor — is worth understanding even if you don’t adopt this exact stack. It’s a clear example of how to build reliable AI systems by minimizing ambiguity and maximizing explicit contracts between components.
→ GitHub Repo: FareedKhan-dev/claude-code-from-scratch ⭐ 132 · Python