Code Agents Playbook

A deep dissection of Claude Code's architecture for engineers building AI code agents

What This Is

Educational material derived from analysis of the Claude Code CLI (~200K LOC TypeScript). It is not a clone, tutorial, or product — it is a reference architecture for production AI code agents (patterns, design trade-offs, runnable Python in code-samples/). No Claude Code source — all code here is original to this repo (docs, diagrams, and code-samples/).

Chapter structure (same across all parts — from intuition to detail):

Reading order within a chapter is easier at the top (Overview) and more specific toward the bottom (Insights, samples, Build your own).

Who This Is For

• Engineers building their own code agents — use this as a blueprint
• AI agents consuming this as documentation for building custom systems — see AGENTS.md
• Anyone curious about how a production LLM tool system works under the hood

How to use this material

Mission & Contributing

Mission: Grow into a full Playbook for reliable, production-grade open-source coding agents — one reference for architecture, safety, operations, and implementation patterns instead of scattered tribal knowledge.

Contributing: Extend chapters, propose edits, fix mistakes, clarify text, or improve code-samples; issues and pull requests keep this resource accurate for everyone building coding agents in the open.

How to Read This

The chapters are ordered from fundamentals to advanced topics. Each chapter is self-contained but builds on earlier concepts.

Recommended path: Read Part I first. Then jump to whichever Part II–IV chapter matches what you're building.

Table of Contents

Part I: Foundations

Part II: Core Systems

Part III: Advanced Patterns

Part IV: Production

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        USER / IDE                               │
│                   (Terminal, VS Code, JetBrains)                │
└──────────────┬──────────────────────────────┬───────────────────┘
               │ Input                        │ Bridge Protocol
               ▼                              ▼
┌──────────────────────┐        ┌─────────────────────────┐
│    REPL / React+Ink  │◄──────►│     IDE Bridge          │
│    (screens, input,  │        │  (JWT, sessions,        │
│     permissions UI)  │        │   transport)            │
└──────────┬───────────┘        └─────────────────────────┘
           │ handlePromptSubmit()
           ▼
┌──────────────────────────────────────────────────────────────┐
│                    QUERY ENGINE                               │
│  ┌────────────────────────────────────────────────────────┐  │
│  │              query() — async generator loop             │  │
│  │                                                        │  │
│  │  ┌──────────┐    ┌───────────┐    ┌────────────────┐  │  │
│  │  │ API Call  │───►│ Stream    │───►│ Tool Execution │  │  │
│  │  │ (retry,   │    │ (SSE,     │    │ (concurrent,   │  │  │
│  │  │  fallback)│    │  thinking)│    │  permissions)  │  │  │
│  │  └──────────┘    └───────────┘    └───────┬────────┘  │  │
│  │       ▲                                    │          │  │
│  │       └────────────────────────────────────┘          │  │
│  │              LOOP until end_turn / max turns           │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
│  │  Compaction   │  │  Token       │  │  Recovery        │  │
│  │  (full/micro/ │  │  Budget      │  │  (collapse →     │  │
│  │   partial)    │  │  Tracking    │  │   compact →      │  │
│  │              │  │              │  │   max_tokens)    │  │
│  └──────────────┘  └──────────────┘  └──────────────────┘  │
└──────────────────────────────────────────────────────────────┘
           │                              │
           ▼                              ▼
┌─────────────────────┐     ┌──────────────────────────────┐
│       TOOLS          │     │        SERVICES              │
│  ┌───────────────┐  │     │  ┌────────┐  ┌───────────┐  │
│  │ BashTool      │  │     │  │ MCP    │  │ Memory    │  │
│  │ FileEditTool  │  │     │  │ Client │  │ (memdir,  │  │
│  │ FileReadTool  │  │     │  └────────┘  │  extract)  │  │
│  │ GrepTool      │  │     │  ┌────────┐  └───────────┘  │
│  │ AgentTool ────┼──┼──►  │  │ OAuth  │  ┌───────────┐  │
│  │ SkillTool     │  │     │  └────────┘  │ Analytics │  │
│  │ MCPTool       │  │     │  ┌────────┐  │ (events,  │  │
│  │ SendMessage   │  │     │  │ API    │  │  flags)   │  │
│  │ ...40+ tools  │  │     │  │ Client │  └───────────┘  │
│  └───────────────┘  │     │  └────────┘                  │
└─────────────────────┘     └──────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────┐
│           PERMISSION SYSTEM              │
│  Modes: default │ plan │ auto │ bypass  │
│  Rules: allow/deny lists, classifiers   │
│  Handlers: interactive, coordinator,    │
│            swarm worker                 │
└─────────────────────────────────────────┘

Key Principles Extracted from Claude Code

1. Generator-based loops — async function* for streaming, backpressure, and cancellation
2. Immutable permission contexts — freeze with DeepImmutable<> to prevent self-modification
3. Cache-safe forking — share rendered system prompt bytes, not prompt builders
4. Feature gates — compile-time dead code elimination via feature() flags
5. File-based coordination — disk I/O over IPC for cross-process durability
6. PII safety at the type level — verbose type names force conscious verification
7. Recovery cascades — try the cheapest fix first, escalate to expensive
8. Speculative work — run classifiers/prefetch during blocking operations
9. Task budget after compaction — keep API-side task_budget.remaining aligned with the client when autocompact hides prior context
10. Tool continuation from blocks — treat assembled tool_use blocks as the signal to continue, not stop_reason alone

Tech Stack (Original)

Code Samples

Every chapter includes runnable Python code samples that implement the patterns from Claude Code, adapted to Python idioms:

• asyncio for async generators
• pydantic for schema validation
• contextvars for context isolation
• dataclasses / Protocol for tool contracts

These are educational implementations — simplified but faithful to the original design.

Run the samples: from the repository root, install dependencies once with pip install -r docs/code-samples-requirements.txt, then run any sample with python3 docs/<chapter-folder>/code-samples/<file>.py (or python if that is your interpreter).

Disclaimer

This educational material is based on analysis of Claude Code CLI source code that was publicly exposed via a source map file in the npm registry on March 31, 2026. All original source code is the property of Anthropic. This repository is unofficial and not affiliated with Anthropic.

The purpose is strictly educational: understanding patterns, architecture, and design decisions in production AI agent systems. Code samples in this repository are original Python implementations inspired by the patterns — not copies of the proprietary TypeScript source.

Built with curiosity. Powered by reverse engineering.