Inside Claude Code: A Deep Dive into Its Powerful Agent Architecture

Project Overview – Claude Code consists of over 510 000 lines of TypeScript spread across modules such as utils (35.2% of the code), components (15.9%), services (10.5%), and a rich set of tools (≈50 000 lines). The core responsibilities include infrastructure (permissions, Bash security, message handling, Git, MCP) and a React terminal UI.

Two‑Layer Agent Loop

The agent loop is implemented as an implicit state machine with seven recovery paths and ten termination conditions. It is split into two layers: QueryEngine manages session state, transcript persistence, SDK protocol adaptation, and usage accounting, while queryLoop handles a single round of API calls and tool execution. Communication between the layers uses an AsyncGenerator, allowing back‑pressure, cancellable .return() semantics, and seamless streaming of sub‑agent results.

Five Design Principles

Tool‑as‑Capability Boundary – An agent can only perform actions that have an explicit tool; adding a capability means adding a tool.

Fail‑Closed Security Defaults – Tools are non‑concurrent, non‑read‑only, and require explicit permission confirmation by default.

Context Engineering > Prompt Engineering – The full context (segment cache, dynamic injection, multi‑layer compression) is assembled each turn instead of a simple prompt.

Composability – Sub‑agents reuse the parent’s query() function; MCP tools share the same permission checks.

Compile‑time Elimination > Runtime Checks – Bun’s feature() macro removes disabled code paths entirely from the bundle.

Message Pre‑Processing Pipeline

Before each API call, messages pass through a multi‑stage pipeline that follows a “light‑to‑heavy” strategy: cheap local operations first, then expensive API‑driven steps. Auto‑compact is triggered only when the effective context window falls below a calculated threshold (e.g., ~167 k tokens for a 200 k token model). A circuit‑breaker stops Auto‑compact after three consecutive failures, preventing massive token waste.

Tool System and Permissions

Tools are defined by a generic Tool interface with six functional groups and default safety flags ( isConcurrencySafe = false, isReadOnly = false, isDestructive = false, checkPermissions = allow). The permission pipeline evaluates requests in a strict order, giving user‑explicit ask rules priority over bypass modes, and protecting sensitive paths (e.g., .git/, .bashrc) even in bypass mode. Three permission handlers ( interactiveHandler, coordinatorHandler, swarmWorkerHandler) manage UI prompts, automatic classification, and mailbox‑based escalation respectively.

Multi‑Agent Collaboration

Claude Code supports three collaboration layers: Sub‑agents (lightweight delegation), Teams/Swarm (peer communication with leader‑brokered UI), and Coordinators (pure orchestration without file access). All coordination goes through a single AgentTool entry point, simplifying the model’s mental load. Fork sub‑agents inherit the full conversation history and system prompt, optimizing prompt‑cache hits by sharing a common prefix and only varying the final instruction block.

System Prompt Engineering

The system prompt is a string[] split into static (global cache) and dynamic (per‑session) sections. Static sections act as the agent’s “constitution,” enforcing minimalism, non‑transferable approvals, and internal‑vs‑external behavior differences. Dynamic sections inject project‑specific CLAUDE.md files, Git status, and MCP instructions, with incremental updates to avoid redundant token usage. Four compression tiers (light, medium, heavy, full) are applied based on token budget, and Auto‑compact and Context Collapse are mutually exclusive to preserve fine‑grained context when needed.

Terminal UI – Custom Ink Engine

Claude Code ships a self‑written React terminal renderer built on Ink. It replaces the original WASM‑based Yoga layout with a pure TypeScript implementation, introduces object pools for characters, styles, and hyperlinks (reset every five minutes), and employs blit optimizations, hardware scrolling (DECSTBM), synchronized updates, double buffering, and line caching to achieve 60 fps rendering even on large screens. The event system mirrors the browser’s capture/bubble model, supporting keyboard, mouse, focus, resize, and terminal‑focus events.

MCP Integration

External capabilities are accessed via a four‑layer MCP client. Server configurations are merged from six sources, de‑duplicated, and exposed as internal tools with names like mcp__<server>__<tool>. Feature flags control dynamic tool discovery, and an McpAuthTool enables in‑conversation OAuth flows when a server returns an authentication error.

Design Reflections

Key takeaways include the power of AsyncGenerator for back‑pressure and cancellation, fail‑closed defaults for security, compile‑time dead‑code elimination, and prompt‑cache‑aware architecture. Areas for improvement are the heavy reliance on a monolithic global state, the cognitive load of the permission system, and the concentration of security logic in BashTool. Future redesign suggestions propose a declarative OPA‑style policy engine, finer‑grained context collapse, structured tool result storage, and modular packaging of the tool, permission, and UI layers.

// src/query.ts:204-217 (simplified)

type State = {
  messages: Message[];
  toolUseContext: ToolUseContext;
  autoCompactTracking: AutoCompactTrackingState | undefined;
  maxOutputTokensRecoveryCount: number;
  hasAttemptedReactiveCompact: boolean;
  pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined;
  turnCount: number;
  transition: Continue | undefined; // why the previous iteration continued
};

The article concludes with a set of design inspirations and critical reflections, offering concrete patterns (AsyncGenerator, fail‑closed defaults, compile‑time dead‑code elimination, prompt‑cache‑aware design) and pointing out improvement opportunities such as reducing global state, simplifying the permission model, and extracting security concerns from BashTool.