The Hidden Blueprint Inside Claude Code: What 512K Lines Exposed

The Hidden Blueprint Inside Claude Code: What 512K Lines Exposed

What if the most powerful coding assistant on the planet had its entire operating manual laid bare? Not the marketing slides. Not the sanitized API docs. The actual source architecture—telemetry pipelines, secret codenames, remote killswitches, and a mode that makes AI commits indistinguishable from human ones.

That's exactly what landed in the open-source repository sanbuphy/learn-coding-agent. A meticulous reverse-engineering effort that dissected roughly 512,664 lines of TypeScript across 1,884 files to expose how Anthropic's Claude Code CLI agent really works under the hood. And what it reveals isn't just impressive engineering—it's a masterclass in production-grade AI agent architecture that every developer building with LLMs needs to study.

The Claude Code architecture documented here goes far beyond the basic "agent loop" tutorials flooding your feed. We're talking about 12 progressive harness mechanisms, 40+ specialized tools, multi-agent swarm coordination, context compression algorithms, and feature flags with names like KAIROS and Numbat that hint at capabilities not yet public. Whether you're building your own coding agent, integrating MCP servers, or simply trying to understand where this technology is headed, this repository is the Rosetta Stone you didn't know existed.

Ready to see what Anthropic doesn't put in the changelog? Let's dive into the blueprint.

What Is sanbuphy/learn-coding-agent?

The learn-coding-agent repository is a technical research and educational compilation focused entirely on CLI agent architecture, with particular emphasis on Claude Code. Created by researcher sanbuphy, this isn't leaked source code—it's something arguably more valuable: a systematic architectural reconstruction derived from publicly available references, community discussions, and deep analysis of Claude Code v2.1.88.

The repository has exploded in developer circles because it answers questions that official documentation deliberately obscures. How does Claude Code manage context windows during marathon coding sessions? What tools can it actually invoke, and how are permissions enforced? Why can't you opt out of certain telemetry? And what's coming next with codenames like Numbat and KAIROS?

What makes this project uniquely powerful is its quadrilingual coverage—deep analysis reports exist in English, Japanese, Korean, and Chinese—reflecting genuine global interest in understanding production agent systems. The repository explicitly prohibits commercial use and positions itself strictly for educational exchange among enthusiasts, with a clear takedown mechanism for any rights holders.

The timing couldn't be more relevant. As developers rush to build "vibe coding" tools and autonomous coding agents, most are rediscovering problems that Claude Code has already solved: permission escalation, context overflow, multi-agent coordination, and safe tool execution. This repository lets you skip years of painful iteration and study a battle-tested architecture that handles real-world complexity.

Key Features: The Engineering That Powers Claude Code

The architecture exposed in this study reveals 12 progressive harness mechanisms that transform a simple LLM API loop into a production-grade coding agent. Here's what makes this system genuinely exceptional:

The Core Agent Loop with Production Hardening At its heart, Claude Code runs a deceptively simple pattern: user message → Claude API → check stop_reason for tool_use → execute tools → append results → loop. But wrapping this minimal loop is where the engineering magic happens. The query.ts file alone—at 785KB the largest single file—contains the orchestration logic that makes this reliable at scale.

40+ Built-in Tools with Sophisticated Lifecycle Management Every tool implements a complete interface: validateInput(), checkPermissions(), call(), plus rendering methods for the terminal UI and AI-facing prompt() descriptions. Tools declare their concurrency safety, destructiveness, and interrupt behavior. This isn't a simple function registry—it's a capability-based security model where BashTool, FileEditTool, AgentTool, and MCPTool each participate in permission flows with granular controls.

Context Compression System When conversations grow long, Claude Code doesn't simply truncate. It employs three compression strategies: autoCompact (summarizes older messages via API call), snipCompact (aggressive trimming with HISTORY_SNIP flag), and contextCollapse (structural restructuring). The system maintains a compact_boundary marker, preserving full fidelity for recent messages while compressing history—critical for maintaining coherence in 100K+ token sessions.

Multi-Agent Architecture with Four Spawn Modes The sub-agent system supports default (in-process), fork (child process with fresh messages), worktree (isolated git worktree + fork), and remote (bridge to containerized environments). Agents communicate via SendMessageTool, coordinate through shared task boards, and can operate in swarm mode where a lead agent delegates to teammates that autonomously claim tasks.

MCP (Model Context Protocol) Integration Claude Code functions as both MCP client and server, supporting stdio, SSE, HTTP, WebSocket, and SDK transports. The MCPConnectionManager handles OAuth 2.0 authentication, cross-app access (XAA/SEP-990), and dynamic tool registration with the mcp__<server>__<tool> naming convention.

Session Persistence with JSONL Transcripts Every session writes append-only JSONL logs to ~/.claude/projects/<hash>/sessions/, enabling --continue, --resume <id>, and --fork-session operations. The write strategy is deliberately tiered: user messages block for crash recovery, assistant messages fire-and-forget with ordering preservation.

Use Cases: Where This Architecture Shines

Building Your Own Production Coding Agent

If you're developing a CLI coding assistant, this architecture provides a complete reference implementation. The 12 progressive harness mechanisms show exactly how to evolve from "simple loop" to "production system" without architectural rewrites. The permission system alone—with its hooks, rules engine, and interactive prompts—solves safety problems that sink most agent projects.

Understanding MCP Server Integration Patterns

The MCP documentation is sparse on real-world implementation. This study shows how Claude Code handles server discovery, client lifecycle management, reconnection with exponential backoff, and dynamic schema loading—essential knowledge if you're building MCP servers or clients.

Researching AI Agent Safety and Transparency

The deep analysis reports cover telemetry collection (two analytics sinks including Datadog, environment fingerprinting, no UI opt-out), undercover mode (AI attribution stripping in public repos), and remote control capabilities (hourly settings polling, killswitches that can force app exit). For researchers studying AI transparency and user autonomy, this is primary source material.

Designing Context Management for Long-Horizon Tasks

The compaction strategies, task persistence system, and background task mechanisms (DreamTask for "thinking", LocalShellTask for daemon execution) demonstrate how to maintain coherence across hours-long coding sessions—a problem every serious agent builder encounters.

Multi-Agent System Architecture

The swarm mode, team protocols, and worktree isolation patterns provide a proven design for collaborative AI systems. If you're building agent teams that need to coordinate without single-point bottlenecks, study the coordinator mode and InProcessTeammateTask implementations.

Step-by-Step: Exploring the Repository Architecture

While this is a research repository rather than installable software, here's how to extract maximum value from the study:

Clone and Navigate the Structure

# Clone the research repository
git clone https://github.com/sanbuphy/learn-coding-agent.git
cd learn-coding-agent

# Explore the deep analysis reports (English)
cd docs/en
ls -la
# 01-telemetry-and-privacy.md
# 02-hidden-features-and-codenames.md
# 03-undercover-mode.md
# 04-remote-control-and-killswitches.md
# 05-future-roadmap.md

Understanding the Source Tree Reference

The repository provides a complete directory map of Claude Code's architecture. Key entry points to study:

# The main agent loop - largest file at ~785KB
# src/query.ts - Core while-true loop with tool execution

# Query engine for SDK/headless usage
# src/QueryEngine.ts - AsyncGenerator-based streaming lifecycle

# Tool system foundation
# src/Tool.ts - Interface definition and buildTool factory
# src/tools.ts - Registry with 40+ built-in tools

# Permission and state management
# src/state/AppStateStore.ts - Centralized state with React↗ Bright Coding Blog integration
# src/utils/permissions/ - Rule engine for tool authorization

Reading the Architecture Diagrams

The repository contains multiple ASCII architecture diagrams. Study them in this order for progressive understanding:

1. "The Agent Pattern" - Understand the minimal loop before production wrapping
2. "Architecture Overview" - See Entry → Query Engine → Tools/Services/State separation
3. "Data Flow: A Single Query Lifecycle" - Trace complete request path with compaction and persistence
4. "Tool System Architecture" - Study the full tool lifecycle interface
5. "The 12 Progressive Harness Mechanisms" - See how features layer from s01 to s12

Accessing Multilingual Reports

# Compare insights across languages
cd docs
ls */01*
# en/01-telemetry-and-privacy.md
# ja/01-テレメトリとプライバシー.md
# ko/01-텔레메트리와-프라이버시.md
# zh/01-遥测与隐私分析.md

REAL Code Examples from the Architecture Study

The repository contains extensive architectural documentation with concrete implementation patterns. Here are critical excerpts with detailed analysis:

Example 1: The Minimal Agent Loop (The Foundation)

This is where everything starts—the core pattern that Claude Code wraps with production mechanisms:

// From src/query.ts - the fundamental agent loop pattern
// This is NOT the full 785KB file, but its architectural essence

// The loop that drives all agent behavior
while (true) {
  // Send conversation history to Claude API with available tools
  const response = await claudeAPI.messages.create({
    model: mainLoopModel,           // Active model from AppState
    messages: normalizedMessages,   // After compaction, stripped of UI fields
    tools: availableTools.map(t => t.prompt()),  // AI-facing descriptions
    system: systemPromptParts,      // Tools, permissions, CLAUDE.md memory
  });

  // Check if the model wants to use a tool
  if (response.stop_reason === "tool_use") {
    // Extract tool calls from response content blocks
    const toolUses = response.content.filter(
      block => block.type === "tool_use"
    );
    
    // Execute tools and collect results
    const toolResults = await streamingToolExecutor.run(toolUses, {
      // Partition: concurrent-safe tools run in parallel
      // serial tools execute sequentially for safety
      partitionByConcurrency: true,
      checkPermissions: (tool, input) => canUseTool(tool, input, permissionContext)
    });
    
    // Append results to conversation history and loop back
    messages.push(...toolResults);
    
    // Persist for crash recovery (blocking write for user messages)
    await recordTranscript(toolResults);
  } else {
    // Model returned text response - yield to user and break
    yield {
      type: "result",
      content: response.content,
      usage: response.usage,
      cost: costTracker.accumulate(response.usage),
      session_id: currentSessionId
    };
    break;
  }
}

Why this matters: This loop is deceptively simple, but every production failure mode emerges from it. The streamingToolExecutor handles parallel execution safety. The canUseTool check implements the full permission pipeline. The recordTranscript call enables session recovery. Understanding this loop is prerequisite to understanding everything layered on top.

Example 2: Tool Interface with Security Lifecycle

The buildTool factory enforces consistent security and rendering behavior:

// From src/Tool.ts - the complete tool interface

interface Tool<Input, Output, Progress> {
  // === LIFECYCLE METHODS ===
  
  // Reject malformed inputs before any expensive operations
  validateInput(input: unknown): asserts input is Input;
  
  // Tool-specific authorization (e.g., path sandboxing for BashTool)
  checkPermissions(input: Input, context: PermissionContext): PermissionResult;
  
  // Execute the tool and return structured result
  call(input: Input): Promise<Output>;
  
  // === CAPABILITY DECLARATIONS ===
  
  // Can this tool run concurrently with others?
  isConcurrencySafe(): boolean;
  
  // Does this tool modify state? (affects undo, warnings)
  isReadOnly(): boolean;
  
  // Can this operation be reversed? (file edits yes, bash rm -rf no)
  isDestructive(): boolean;
  
  // What happens when user interrupts? (cancel vs block)
  interruptBehavior(): "cancel" | "block";
  
  // === AI-FACING DESCRIPTIONS ===
  
  // Description injected into system prompt for model to use
  prompt(): ToolDefinition;
  
  // Dynamic description based on current state
  description(): string;
  
  // Format tool result for API consumption
  mapToolResultToAPI(output: Output): ToolResultBlock;
  
  // === TERMINAL RENDERING (React/Ink) ===
  
  renderToolUseMessage(input: Input): React.ReactNode;
  renderToolResultMessage(output: Output): React.ReactNode;
  renderToolUseProgressMessage(progress: Progress): React.ReactNode;
}

// Factory function providing safe defaults
function buildTool<Input, Output, Progress>(
  definition: ToolDefinition
): Tool<Input, Output, Progress> {
  // Ensures all tools implement consistent behavior
  // Default: non-concurrent, read-only, non-destructive, cancel on interrupt
  return {
    isConcurrencySafe: () => false,
    isReadOnly: () => true,
    isDestructive: () => false,
    interruptBehavior: () => "cancel",
    ...definition  // Override defaults with tool-specific behavior
  };
}

Why this matters: The isDestructive() and isReadOnly() declarations enable the file history snapshot system—Claude Code can offer undo for file edits but warns irreversibly for bash commands. The concurrency safety flag drives the StreamingToolExecutor's parallelization decisions. This interface is the contract that makes 40+ tools composable and safe.

Example 3: Context Compression with Compact Boundary

The compaction system prevents context window overflow during long sessions:

// From services/compact/ - context management strategy

interface CompactedContext {
  // Summary of older conversation, generated by compact API call
  summary: string;
  
  // Marker separating summarized from full-fidelity history
  compactBoundary: CompactBoundaryMarker;
  
  // Recent messages preserved at full detail
  recentMessages: Message[];
}

async function autoCompact(messages: Message[]): Promise<Message[]> {
  const tokenCount = await estimateTokenCount(messages);
  const threshold = getContextWindowBudget() * 0.8;  // 80% threshold
  
  if (tokenCount < threshold) {
    return messages;  // No compaction needed
  }
  
  // Find optimal split point (preserve recent N messages)
  const splitIndex = findCompactSplitPoint(messages);
  const olderMessages = messages.slice(0, splitIndex);
  const recentMessages = messages.slice(splitIndex);
  
  // Generate summary via compact API call (cheaper model, focused task)
  const summary = await claudeAPI.messages.create({
    model: "claude-3-haiku-20240307",  // Cost-optimized for summarization
    messages: [{
      role: "user",
      content: `Summarize this conversation for context preservation. 
                Preserve: file paths, decisions made, errors encountered, 
                current task state. Omit: reasoning steps, failed attempts.`
    }, {
      role: "user",  // Pass history as context
      content: formatMessagesForSummary(olderMessages)
    }],
    max_tokens: 2000
  });
  
  // Reconstruct with boundary marker for potential decompression
  return [
    {
      type: "system",
      subtype: "compact_summary",
      content: summary.content[0].text
    },
    {
      type: "system",
      subtype: "compact_boundary",
      originalMessageCount: olderMessages.length,
      timestamp: Date.now()
    },
    ...recentMessages
  ];
}

// Three strategies available, controlled by feature flags
const compactionStrategies = {
  autoCompact,      // Summarize older messages
  snipCompact,      // Aggressive trimming (HISTORY_SNIP flag)
  contextCollapse   // Structural restructuring (CONTEXT_COLLAPSE flag)
};

Why this matters: This is how Claude Code handles multi-hour coding sessions without losing coherence. The compact_boundary marker enables potential future decompression. The use of a cheaper model for summarization controls costs. The 80% threshold provides headroom for the current turn's generation.

Example 4: Permission System with Pre-Tool Hooks

The multi-layer permission flow prevents dangerous operations:

// From utils/permissions/ and Tool.ts - complete permission pipeline

async function canUseTool(
  tool: Tool,
  input: unknown,
  context: ToolPermissionContext
): Promise<PermissionDecision> {
  
  // LAYER 1: Input validation (cheap, reject early)
  try {
    tool.validateInput(input);
  } catch (e) {
    return { decision: "deny", reason: "invalid_input", error: e };
  }
  
  // LAYER 2: Pre-tool hooks (user-defined shell commands)
  // settings.json can define hooks that approve/deny/modify
  const hookResult = await executePreToolUseHooks(tool.name, input, context);
  if (hookResult.decision !== "pass") {
    return hookResult;  // Hook approved or denied
  }
  
  // LAYER 3: Permission rules (pattern matching)
  const ruleMatch = findMatchingRule(tool.name, input, context);
  if (ruleMatch) {
    switch (ruleMatch.action) {
      case "always_allow": return { decision: "allow", source: "rule" };
      case "always_deny": return { decision: "deny", source: "rule" };
      case "always_ask": break;  // Fall through to interactive
    }
  }
  
  // LAYER 4: Interactive prompt (terminal UI)
  if (!context.autoApproveAll) {
    const userChoice = await renderPermissionPrompt(tool, input, {
      options: ["allow_once", "allow_always", "deny"],
      showPreview: tool.isDestructive()  // Extra warning for rm, etc.
    });
    
    if (userChoice === "allow_always") {
      updateAlwaysAllowRules(tool.name, input);  // Persist decision
    }
    return { decision: userChoice.startsWith("allow") ? "allow" : "deny" };
  }
  
  // LAYER 5: Tool-specific authorization
  return tool.checkPermissions(input, context);
}

Why this matters: This five-layer defense is why Claude Code can safely execute bash commands and file edits. The pre-tool hooks enable enterprise policy enforcement. The rule persistence learns from user decisions. The interactive layer maintains human oversight for novel operations.

Example 5: Feature Flag System with Compile-Time Elimination

Claude Code uses Bun's compile-time features for zero-overhead feature gating:

// Compile-time dead code elimination via bun:bundle
import { feature } from "bun:bundle";

// These are evaluated at BUILD time, not runtime
// False branches are completely stripped from the bundle

if (feature("KAIROS")) {
  // Fully autonomous agent mode with <tick> heartbeats
  // push notifications, PR subscriptions
  // STRIPPED from public builds
  import("./kairos/autonomousMode");
}

if (feature("VOICE_MODE")) {
  // Push-to-talk voice input/output
  // Gated in public, ready for release
  import("./voice/voiceMode");
}

if (feature("DUMP_SYSTEM_PROMPT")) {
  // Extract full system prompt for analysis
  // Internal-only (ant employee) feature
  export function dumpSystemPrompt() { /* ... */ }
}

// Runtime gates for A/B experiments
const growthbook = await getGrowthBookClient();
const useNewCompact = growthbook.isOn("context_collapse_v2");

Why this matters: The feature() system explains how Claude Code ships experimental capabilities without bundle bloat. Internal features (requiring process.env.USER_TYPE === 'ant') are physically absent from public builds. GrowthBook enables A/B testing at runtime. This dual-gate system balances security, performance, and rapid iteration.

Advanced Usage & Best Practices

Study the 12 Harness Mechanisms Progressively

Don't jump to swarm mode before understanding the basic loop. The repository explicitly structures learning as s01 through s12—each mechanism builds on previous ones. Try implementing s01-s03 in your own project before studying s09-s12.

Analyze the Permission Model for Your Domain

The five-layer permission system (validation → hooks → rules → interactive → tool-specific) is domain-agnostic. If you're building any agent that executes code, adapts files, or makes API calls, adapt this pattern. The isDestructive() and interruptBehavior() declarations are particularly underappreciated design patterns.

Implement Context Compaction Before You Need It

Most agent projects add compaction after hitting context limits in production. Study the three strategies (autoCompact, snipCompact, contextCollapse) and implement the simplest that fits your use case early. The compact_boundary marker pattern enables future extensibility.

Use Branded Types for API Safety

The repository highlights SystemPrompt and asSystemPrompt() as branded types preventing string/array confusion. This TypeScript pattern catches entire classes of bugs at compile time—adopt it for your message types.

Monitor Feature Flag Patterns for Capability Gating

The combination of compile-time elimination (Bun feature()) and runtime experimentation (GrowthBook) provides a template for shipping safely. Use compile-time gates for security-sensitive or bundle-critical features; use runtime gates for A/B testing user-facing behavior.

Comparison: Claude Code vs. Alternative Approaches

Why Claude Code's architecture wins: The integration depth. Individual features exist elsewhere, but the composition—compaction feeding into persistent tasks feeding into sub-agents with isolated worktrees—is uniquely sophisticated. The permission system isn't bolted on; it's woven through every tool lifecycle. For developers building serious agent systems, this architecture provides the reference implementation that piecing together tutorials cannot match.

FAQ: Common Developer Questions

Is this leaked source code from Anthropic?

No. The repository explicitly states all materials are compiled from publicly available references and community discussions. It's architectural research and analysis, not a code dump. The deep analysis covers v2.1.88 based on observable behavior and reverse engineering.

Can I use this to build a commercial Claude Code competitor?

No. The repository's license strictly prohibits commercial use. It's for educational and research purposes only. However, studying the architecture patterns and implementing analogous systems from scratch with your own code is standard practice.

What is "undercover mode" and should I worry about it?

Undercover mode automatically strips AI attribution from commits in public repositories, with the model instructed to "not blow your cover." The study documents this as a transparency concern for open-source communities. There's no documented way for users to force-disable it.

What are the animal codenames (Capybara, Tengu, Numbat)?

These are internal model version identifiers. Capybara v8 maps to a released model, Fennec became Opus 4.6, and Numbat represents the next generation in development. Feature flags use random word pairs to obscure their purpose from casual inspection.

What is KAIROS?

KAIROS is a feature-flagged autonomous agent mode with <tick> heartbeat messages, push notifications, and PR subscription capabilities. It represents a shift toward fully autonomous operation rather than interactive session-based usage.

How does the remote control system work?

Claude Code polls /api/claude_code/settings hourly. This enables managed settings, killswitches (6+ documented, including bypass permissions and analytics sink changes), and model overrides. Rejecting a dangerous change can cause the application to exit.

Why can't I opt out of first-party telemetry?

The study documents two analytics sinks (first-party and Datadog) with environment fingerprinting, process metrics, and repository hashing on every event. While OTEL_LOG_TOOL_DETAILS=1 enables full capture, there's no UI-exposed opt-out for the first-party logging—this is documented behavior, not a bug.

Conclusion: The Architecture Every Agent Builder Must Study

The sanbuphy/learn-coding-agent repository is more than a curiosity about Claude Code's internals—it's a graduate course in production AI agent engineering. The 12 progressive harness mechanisms, from basic loop to autonomous swarm coordination, provide a roadmap that would take years to discover through trial and error.

What strikes me most is the intentional layering. Each mechanism solves one problem cleanly: s03 for planning, s06 for context limits, s09 for team scaling. The permission system isn't an afterthought—it permeates every tool interface. The compaction strategies acknowledge that context windows are a fundamental constraint, not a temporary limitation.

For developers building the next generation of coding agents, this study offers something invaluable: validated patterns from a system that clearly works at scale. The 512K lines, 40+ tools, and 80+ slash commands aren't bloat—they're the accumulated complexity of handling real user workflows safely.

My recommendation? Star this repository. Read the deep analysis reports in your preferred language. Implement the core loop and permission system in a side project. And watch for Numbat and KAIROS—the architecture suggests autonomous capabilities are closer than the marketing implies.

The future of software development is being built by agents. Understanding how the best ones work isn't optional—it's competitive advantage.

→ Explore the full architecture study: github.com/sanbuphy/learn-coding-agent