Claude Code Architecture: A Multi-Agent System in Your Terminal

Digital Strategy Review | 2026

Deep Dive into Claude Code `src` Architecture: Why Building a Terminal Assistant as a Multi-Agent Runtime is a Game Changer

By Uncle Fruit · Reading Time / 8 Min

Claude Code Source Architecture Overview

Foreword

If you only look at the product surface, Claude Code is easily mistaken for a chat assistant in the terminal. However, after diving into the src directory, my takeaway is clear: its core isn’t “chatting”—it’s about treating Agents as schedulable, isolated, recoverable, and observable system objects.

Opening: The Verdict

If you only look at the product surface, Claude Code is easily mistaken for a “model caller wrapped in a terminal UI.” But after reading through the src, my conclusion is definitive: its core isn’t “chatting”—it’s about transforming Agents into schedulable, isolated, recoverable, observable, and collaborative runtime objects.

In other words, it doesn’t just “embed a few AI features” into a CLI; it builds a complete agent runtime within the CLI:

01 User Interaction Layer: Handles REPL, commands, permission prompts, task views, and the status bar.

02 Inference Loop Layer: Manages prompt organization, model calls, context compression, tool execution, stop hooks, and budget control.

03 Execution System Layer: Manages tools, tasks, sub-agents, team agents, remote agents, worktree isolation, permission synchronization, and state persistence.

04 Cross-cutting Capabilities: MCP, plugins, skills, memory, LSP, telemetry, remote control, sandboxing, and security policies.

This is why its src doesn’t look like a traditional CLI project; it looks more like a “distributed agent control plane in the terminal.”

Mermaid Diagram 1

If I had to summarize this system in engineering terms, I would say:

The true innovation of Claude Code is not just “supporting sub-agents,” but unifying sub-agents, background tasks, remote tasks, team collaboration, permission approvals, context reuse, and result notifications into a shared task and tool semantic framework.

This article is divided into two parts:

01 Explaining the overall src architecture to answer “how this system actually runs.”

02 Presenting the 10 most useful and innovative agent implementation highlights, ranked by importance.

Key anchor points mentioned in the text come from these files:

• src/entrypoints/cli.tsx • src/main.tsx • src/query.ts • src/tools.ts • src/services/tools/toolOrchestration.ts • src/tools/AgentTool/AgentTool.tsx • src/tools/AgentTool/runAgent.ts • src/tasks/LocalAgentTask/LocalAgentTask.tsx • src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx • src/utils/swarm/spawnInProcess.ts • src/utils/swarm/inProcessRunner.ts • src/state/AppStateStore.ts • src/tools/AgentTool/built-in/*.ts • src/tools/AgentTool/agentMemory.ts • src/tools/AgentTool/forkSubagent.ts

I. Don’t Rush to the Agents: Look at the Startup

Many architectural issues are obvious from the entry point. This is especially true for Claude Code.

src/entrypoints/cli.tsx is not a “simple forwarder to main.” It is a performance-sensitive scheduler in its own right. It does three critical things:

01 Handles environment variables and feature gates at the earliest stage.

02 Uses fast-paths to intercept paths that don’t require a full CLI startup.

03 Dynamically imports heavy modules only when a full interactive runtime is truly needed.

This means the author clearly categorized startup paths into two types:

• Light Path: Performs single actions, such as --version, daemon workers, bridges, background session management, template commands, and environment runners.

• Heavy Path: Enters the full interactive runtime.

This isn’t just startup optimization; it reveals a deeper design choice: Claude Code is not a monolithic entry point, but a set of core infrastructure shared by multiple operating modes. The CLI is just one shell; background workers, remote runners, bridges, and headless runners are all different entry points into the same system.

This step is crucial because, as you’ll see later, its agents don’t just live in the “current command-line session.” They might live in:

• The current foreground REPL • Local background tasks • In-process teammates • Tmux pane teammates • Independent worktrees • Remote CCR sessions

If the entry layer hadn’t clearly separated these modes, the agent system would inevitably conflict.

II. `main.tsx` Isn’t a “Page Entry”—It’s the Assembly Line

Many people see main.tsx and instinctively think it’s a UI entry point. In reality, it’s a runtime assembler.

This file is quite large, but that’s not a bad thing. Its size indicates that it is responsible for “system assembly” rather than business logic. Reading through it, I found it performs six main categories of tasks:

1. Warming Up Environments That Affect the Main Loop

main.tsx starts with several deliberate actions: • Starting profiler checkpoints • Pre-fetching MDM (Managed Device Management) data • Pre-fetching keychain data

This isn’t just “optimizing startup speed.” It reflects a mature understanding of interactive systems: slow I/O that blocks the initial experience should be triggered as early as possible, ideally in parallel with other imports.

2. Initializing Config, Policy, Auth, Telemetry, and GrowthBook

At this layer, main.tsx pulls up global capabilities: • Config, managed settings, policy limits, auth/OAuth, growthbook, analytics, plugins, MCP, skills, commands, model selection, and permission modes.

The order matters. For example, without auth, remote features and policy judgments are incomplete. Without tool permission context, the generated tool pool might overstep its bounds.

3. Assembling Commands, Tools, MCP, Plugins, and Agent Definitions

main.tsx calls getTools(...), agent definition loading logic, MCP connections, plugin startup, and skill initialization. This determines the “capability surface” visible to the current session.

4. Establishing a Global State Repository

The AppState in src/state/AppStateStore.ts is worth a close look. It doesn’t just manage the UI; it unifies: • Settings, main model state, permission context, task collections, agent registries, foreground/viewing agents, MCP clients, plugin states, agent definitions, todos, notifications, and REPL VM context.

5. Launching the REPL

Multiple launchRepl(...) calls indicate that main.tsx doesn’t just follow one path, but enters different versions of the REPL based on recovery, remote, or initialization results.

6. Acting as a Bridge for Various Modes

main.tsx understands local interactive modes, background sessions, remote viewers, bridge modes, assistant/kairos modes, worktree modes, and teammate/swarm modes. It acts as a control room, assembling the system into the version required for the current session.

III. The Real Heart Isn’t the UI—It’s `query.ts`

If main.tsx is the assembly line, src/query.ts is the heart.

The key value of this implementation is that it’s not “send a request, get a response,” but a complete agentic turn loop:

01 Collect messages. 02 Organize system prompt / user context / tool context. 03 Call the model. 04 Handle streaming output. 05 Extract tool use. 06 Execute tools. 07 Feed tool results back into the message stream. 08 Continue to the next turn if necessary. 09 Handle interruptions, compression, budgets, hooks, and recovery.

1. Explicit Distinction Between Immutable Params and Mutable Loop State

query.ts clearly separates immutable parameters from state that changes across iterations. This prevents state management from becoming a disaster during complex turns involving multiple tool uses, compression, and exception recovery.

2. Native Support for “Long Turns”

The design core isn’t “chat history,” but “is the current task complete?” This is why the code includes auto-compact, micro-compact, token budgets, and stop hooks.

3. Tool Execution is Part of the Main Loop

Tools aren’t “external add-ons”; they are an intrinsic part of the query loop. This allows for natural implementation of tool result budget control, content replacement/compression, and tool progress messages.

Claude Code Runtime Layering

IV. The Tool System: Not Just Function Calling, But a Governed Execution Plane

Looking at src/tools.ts, the most important aspects are:

1. Tools are Dynamically Clipped

Tools aren’t fixed. They are constructed based on feature gates, user type, LSP status, worktree status, swarm status, plugin/MCP status, and permission modes.

2. Tools are Part of Prompt Engineering

Since the system prompt exposes tool definitions to the model, the tool list constitutes the model’s “operational worldview.” Claude Code carefully manages which tools are exposed, hidden, or restricted by permission.

3. Tool Execution is Observable and Statistical

Tool execution paths handle telemetry, permission decisions, hooks, tracing, progress, and error classification.

V. The “Beautiful Cut”: Concurrency Safety

src/services/tools/toolOrchestration.ts is small but invaluable. It automatically batches tool calls based on concurrency safety: read-only tools run in parallel, while write-heavy tools run serially. This offloads complexity from the model to the runtime.

VI. The Task System: Treating Agents as “Task Entities”

In Claude Code, an agent is not just a function result or a transcript; it is a Task.

1. Unified Identity and Lifecycle

Every task has an ID, type, status, description, and start/end time.

2. Output Files are First-Class Citizens

Tasks have their own outputFile. This allows for recovery, notifications, and sidechain transcripts, enabling background agents to function without a persistent foreground UI.

3. Notification System Coupled with Task State

When a task completes, fails, or stops, it generates a <task-notification> message, allowing the main agent to receive updates without blocking.

VII. AgentTool: The Gateway to Multi-Agent Systems

src/tools/AgentTool/AgentTool.tsx is the core facade for multi-agent design. It exposes a unified interface (AgentTool) while routing tasks to different backends (local, teammate, fork, remote, worktree) based on conditions.

Agent Runtime Relationship

VIII. `runAgent.ts`: How Claude Code “Runs” an Agent

runAgent.ts handles the “driving.” It ensures agents aren’t “naked” but start with: • Dedicated context (prompt, tools, models, MCP servers). • Incremental MCP mounting (agents can declare their own needs). • Persistent transcripts (traceable and recoverable).

IX. Built-in Agent Definitions: Elevating “Roles” to Data

src/tools/AgentTool/loadAgentsDir.ts treats agents as loadable, composable, and plugin-based configuration objects rather than hardcoded roles. An agent definition includes behavior boundaries, tool permissions, memory strategies, and isolation policies.

X. The REPL: The Unified Control Desk

src/screens/REPL.tsx is the “Unified Interaction Control Plane.” Whether it’s a main agent, background agent, teammate, or remote session, the user interacts with them through a single, unified terminal interface.

Mermaid Diagram 2

XI. Three Layers of Agent Forms

Ordinary Sub-Agents: Run in the local query loop.
In-Process Teammates: Run in the same Node.js process with context isolation.
Isolated Agents: Worktree/Remote agents for stronger isolation and longer runtimes.

Mermaid Diagram 3

XII. Why the Permission System Works

The permission system isn’t a patch; it’s the main path. By using ToolUseContext and ToolPermissionContext, the system ensures that while workers can initiate actions, final authority remains with the leader’s UI, preventing “permission prompt fatigue.”

XIII. Memory, Hooks, MCP, and Plugins as Extensions

These aren’t add-ons; they are integrated into the agent runtime. • Memory: Three-tier scope (user/project/local). • Hooks: Insert rules at key nodes. • MCP: First-class capability source. • Plugins: Unified extension of capabilities and roles.

XIV. Architecture Summary

CLI Entrypoint -> fast-path dispatch -> main runtime assembly
Main Runtime -> config/auth/policy -> commands/tools/MCP/agents -> REPL
REPL Control Plane -> user input -> message queue -> task panels -> stream rendering
Query Loop -> build prompt -> sample model -> run tools -> compact/recover
Execution Substrate -> Tool execution -> Task framework -> Local/Remote/Teammate tasks
Agent Runtime -> Agent definitions -> AgentTool -> runAgent -> fork/worktree/swarm

XV. 10 Most Innovative Highlights

Agent as Task: Unified lifecycle management.
Semantic Tool Batching: Efficient concurrency.
Fork Subagent Prompt Cache: Optimized for cost.
In-Process Teammate Isolation: Performance/complexity balance.
Leader Approval Model: Centralized decision-making.
Declarative Agent Definitions: Engineering-grade roles.
Agent-Specific MCP: Role-based capability mounting.
Three-Tier Agent Memory: Practical and effective.
First-Class Isolation: Worktree/Remote integration.
Verification Agent: Anti-laziness design.

XVI. Why These Highlights Matter

They solve the five common failure modes of multi-agent systems:

Uncontrollable agents (Solved by Task/Permission/UI).
Concurrency chaos (Solved by Tool Partitioning/Leader Approval).
High costs (Solved by Prompt Caching/Routing).
Non-recoverable errors (Solved by Transcripts/Metadata).
User confusion (Solved by Unified REPL/Notifications).

XVII. Final Summary: The Story of Claude Code

Claude Code’s src tells a story: When you treat Agents as system objects—schedulable, governable, isolated, and collaborative—the entire code structure changes.

It is not just about “putting Claude in the terminal”; it is about building a robust, systemic runtime for AI agents. This is the most valuable lesson for any developer building complex agentic systems.

Deep Dive into Claude Code src Architecture: Why Building a Terminal Assistant as a Multi-Agent Runtime is a Game Changer