Claude Code Codebase Documentation

What This Repository Is

This repository is not the original Anthropic development repository. It is an extracted TypeScript source tree reconstructed from the published source map that shipped with @anthropic-ai/claude-code version 2.1.88.

That matters for two reasons:

1. Some code paths are feature-gated or Anthropic-internal and may not fully work in this extracted environment.
2. The repository is still extremely valuable because it preserves the real architectural shape of the product: boot process, session orchestration, tool execution, permissions, MCP integration, remote control, plugins, skills, and the terminal UI.

If your goal is to understand how Claude Code works internally, this repository is detailed enough to do that.

---

Executive Summary

Claude Code is not a thin wrapper around an LLM API. It is a fairly large agent runtime with these major responsibilities:

• Parse CLI commands and startup modes.
• Initialize auth, config, telemetry, policy, managed settings, proxy, mTLS, and platform-specific state.
• Construct a terminal UI for interactive use.
• Accept user prompts, slash commands, attachments, and system-generated events.
• Build a system prompt and runtime context for each turn.
• Stream model output.
• Detect tool calls emitted by the model.
• Route those tool calls through a permission model and a shared execution context.
• Persist transcripts, file history, attribution state, session metadata, and resumable state.
• Integrate local and remote tools, including MCP servers.
• Support extensibility through plugins, custom skills, and custom agents.
• Support advanced modes such as remote bridge control, background sessions, worktree isolation, and multi-agent coordination.

The architecture is easiest to understand as five layers:

1. CLI and startup layer
2. Session and UI layer
3. Prompt/query orchestration layer
4. Tool and integration layer
5. Persistence and extensibility layer

---

Recommended Reading Order

If you want the shortest path to understanding the system, read these files in order:

1. cli.js
2. src/entrypoints/cli.tsx
3. src/main.tsx
4. src/entrypoints/init.ts
5. src/setup.ts
6. src/QueryEngine.ts
7. src/query.ts
8. src/Tool.ts
9. src/tools.ts
10. src/commands.ts
11. src/utils/processUserInput/processUserInput.ts
12. src/services/tools/toolOrchestration.ts
13. src/utils/sessionStorage.ts
14. src/services/mcp/client.ts
15. src/bridge/bridgeMain.ts

That sequence shows the lifecycle from process startup to a full agent turn, then moves into integrations and persistence.

---

High-Level Architecture

1. CLI and startup layer

This layer decides what mode Claude Code is running in and prepares the process.

Key files:

• cli.js
• src/entrypoints/cli.tsx
• src/main.tsx
• src/entrypoints/init.ts
• src/setup.ts

Responsibilities:

• Fast-path handling for cheap commands like --version.
• Dynamic import of heavier subsystems only when needed.
• Environment setup for normal interactive use, remote bridge mode, daemon mode, background sessions, MCP mode, worktree mode, and special internal features.
• Early startup optimizations such as keychain prefetch, MDM reads, and startup profiling.

2. Session and UI layer

This layer owns the interactive experience.

Key files:

• src/replLauncher.tsx
• src/components/App.tsx
• src/screens/REPL.tsx
• src/state/AppStateStore.ts
• src/ink.ts

Responsibilities:

• Render the terminal UI with Ink and React.
• Maintain interactive session state.
• Show prompts, streaming responses, tool progress, tasks, notifications, bridge state, MCP state, and footer controls.

3. Prompt/query orchestration layer

This is the core agent loop.

Key files:

• src/QueryEngine.ts
• src/query.ts
• src/utils/processUserInput/processUserInput.ts
• src/query/config.ts
• src/query/deps.ts
• src/query/tokenBudget.ts

Responsibilities:

• Turn user input into normalized messages.
• Build system and user context.
• Call the model.
• Stream results.
• Detect tool uses.
• Execute tools.
• Handle continuation, compaction, interruptions, token budgets, and retries.

4. Tool and integration layer

This layer is what makes Claude Code an engineering agent rather than a chat client.

Key files:

• src/Tool.ts
• src/tools.ts
• src/services/tools/toolOrchestration.ts
• src/services/mcp/client.ts
• src/commands.ts

Responsibilities:

• Register all built-in tools.
• Define tool execution context.
• Enforce permissions.
• Integrate MCP servers and expose their tools/resources.
• Support command execution, file editing, web fetch, search, notebook editing, plan/task tools, and agent spawning.

5. Persistence and extensibility layer

This layer lets the system survive across turns and become user-customizable.

Key files:

• src/utils/sessionStorage.ts
• src/history.ts
• src/skills/loadSkillsDir.ts
• src/tools/AgentTool/loadAgentsDir.ts
• src/utils/plugins/pluginLoader.ts

Responsibilities:

• Persist transcripts and session metadata.
• Resume sessions.
• Load skills from markdown.
• Load custom agents.
• Load plugins from marketplaces, seed directories, and local paths.

---

Boot Sequence: How the Process Starts

Step 1: cli.js

The root cli.js file is intentionally tiny. It only loads the built CLI entrypoint from dist/src/entrypoints/cli.js.

This separation exists because the package is shipped as compiled JavaScript, while the repository keeps the extracted TypeScript source.

Step 2: src/entrypoints/cli.tsx

This file is the real bootstrap dispatcher.

Important characteristics:

• It uses dynamic imports aggressively.
• It avoids loading the full application for simple paths.
• It contains many feature-gated branches.

Examples of fast paths handled here:

• --version
• --dump-system-prompt
• bridge and remote-control mode
• daemon mode
• background session commands like ps, logs, attach, kill
• environment-runner and self-hosted-runner modes
• special MCP subprocess modes

The design goal is clear: do not pay the cost of loading the entire app unless the chosen command actually needs it.

Step 3: src/main.tsx

src/main.tsx is the heavyweight application entrypoint.

This file does a very large amount of orchestration:

• Starts early startup profiling.
• Kicks off MDM and keychain prefetch side effects.
• Imports the command registry.
• Imports the tool registry.
• Imports plugin, skill, MCP, telemetry, model, auth, settings, worktree, bridge, task, and UI helpers.
• Sets up command-line parsing with Commander.
• Branches into interactive REPL, headless flows, resume flows, bridge flows, and other operational modes.

One important pattern appears all over this file: feature(...) gates and lazy require(...) calls. This lets the compiled build eliminate internal-only or experimental capabilities.

Step 4: src/entrypoints/init.ts

This file performs global process initialization.

It is responsible for:

• Enabling configs.
• Applying safe config-derived environment variables before trust-sensitive work.
• Configuring CA certs, mTLS, and proxy agents.
• Preconnecting to the Anthropic API.
• Initializing telemetry lazily.
• Initializing remote managed settings and policy limits loading promises.
• Setting up graceful shutdown.
• Registering cleanup tasks.
• Initializing scratchpad directories if enabled.

This is a critical architectural clue: Claude Code treats startup as a staged pipeline with trust-sensitive and non-trust-sensitive work separated.

Step 5: src/setup.ts

setup.ts finishes session-specific startup.

It handles things like:

• setting the current working directory
• capturing hook configuration snapshots
• starting file-changed watchers
• restoring terminal backup state
• creating worktrees and optional tmux sessions
• starting UDS messaging when appropriate

Conceptually, init.ts is global process initialization, while setup.ts is session initialization.

---

Main Operating Modes

Claude Code is really multiple products sharing the same runtime.

Interactive REPL mode

This is the default terminal chat-and-tools experience.

Flow:

1. Parse CLI options.
2. Initialize process and session state.
3. Create AppState.
4. Launch Ink UI.
5. Accept user input.
6. Send turns through the query engine.
7. Render streaming messages and tool output live.

Headless or SDK-style mode

This uses QueryEngine without the full interactive REPL.

Typical use cases:

• scriptable execution
• background agents
• external wrappers
• programmatic embedding

MCP server mode

The repository also exposes entrypoints for MCP-compatible flows. Claude Code is not only an MCP client; parts of it can also participate in external automation protocols.

Bridge or remote-control mode

This turns the local environment into a remotely reachable execution environment and session host.

Background session mode

This supports detached sessions that can be listed, attached to, tailed, or terminated later.

Multi-agent and task mode

Some tools can spawn subagents, teams, remote workers, or background tasks. This is why the runtime has explicit task state, agent registries, and special transcript handling for subagents.

---

Interactive Architecture: REPL, App, and State

REPL launcher

src/replLauncher.tsx is simple but important. It lazy-loads App and REPL, then renders them through the Ink root.

That design keeps the main startup path smaller until the application commits to interactive mode.

App and REPL components

The UI is built with Ink and React. This is significant because it means the runtime is structured like a React app, not like a hand-written curses loop.

Consequences of that decision:

• UI state is component-driven.
• Streaming updates can be rendered declaratively.
• Tool status, message lists, prompts, and side panels compose as React components.
• Complex state transitions are easier to coordinate with a shared store.

App state

src/state/AppStateStore.ts defines an extremely rich application state object.

The state includes:

• settings
• selected model
• permission context
• task registry
• MCP clients, tools, commands, resources
• plugin state
• agent definitions
• file history
• attribution state
• todo lists
• notifications
• elicitation queue
• bridge session state
• prompt suggestion state
• tungsten or browser-related panels
• computer-use MCP state
• REPL tool VM state

This reveals a major design principle:

Claude Code centralizes cross-cutting session state in one durable store because many features need to cooperate in real time. Tool execution, background tasks, permissions, UI overlays, and remote integrations all depend on shared state.

---

Input Processing: How a User Prompt Becomes a Turn

The relevant file is src/utils/processUserInput/processUserInput.ts.

This module sits between raw terminal input and the model query loop.

Responsibilities of input processing

• Accept plain text or structured content blocks.
• Handle images and attachments.
• Recognize slash commands.
• Respect modes like prompt mode versus special input modes.
• Apply hook-based preprocessing.
• Expand pasted content references.
• Produce normalized message objects.

Important design detail: commands are not separate from the conversation model

Claude Code uses both:

• slash commands that are handled locally by the app
• model-driven tool usage that happens inside an assistant turn

That is a strong design choice. It means the product can expose deterministic commands for explicit user actions while still letting the model act agentically inside a turn.

Hook participation

Before a query runs, input processing can invoke hook systems such as user-prompt-submit hooks. These can:

• block a prompt
• add contextual attachments
• stop continuation
• emit system warnings

This gives the system a policy and automation layer before model inference even starts.

---

QueryEngine: Conversation Owner for a Session

The most important file for understanding the core agent architecture is src/QueryEngine.ts.

What QueryEngine owns

QueryEngine is effectively the session brain for one conversation.

It owns:

• mutable message history
• abort controller
• permission denials
• accumulated usage
• read-file cache state
• discovered skills and nested memory tracking

What submitMessage() does

At a high level, submitMessage():

1. Applies the current cwd and session assumptions.
2. Resolves the initial model and thinking configuration.
3. Fetches system prompt parts.
4. Builds user and system context.
5. Optionally injects memory mechanics prompt material.
6. Prepares a ToolUseContext.
7. Processes user input into normalized messages.
8. Calls into query().
9. Streams SDK-style events or final messages back to the caller.

This split is good architecture. QueryEngine owns session-level state, while query.ts owns turn-loop mechanics.

Why this matters

If you were implementing a similar tool, this is a pattern worth copying:

• Session object owns durable state across turns.
• Turn executor owns one turn's streaming and tool loop.

That boundary makes resumability and programmatic embedding much easier.

---

query.ts: The Actual Turn Loop

If QueryEngine is the session owner, src/query.ts is the runtime loop for one agentic turn.

What the query loop does

The exported query() function and its internal queryLoop() function handle the iterative cycle:

1. Normalize input messages.
2. Build query config.
3. Start memory prefetch.
4. Send a request to the model.
5. Stream assistant output.
6. Detect tool uses.
7. Execute tool calls.
8. Append tool results to the message history.
9. Decide whether to continue the loop.
10. Handle compaction, retries, token budgets, or stop conditions.

Important features present in this loop

Compaction

The query loop is designed for long-running sessions. It tracks and triggers context compaction when history becomes too large.

This is not an add-on feature. It is first-class.

That tells you something fundamental about the product: Claude Code assumes sessions are long, stateful, and costly enough that context management must be built directly into the agent runtime.

Recovery behavior

The loop contains logic for handling max_output_tokens and prompt-too-long style errors. It can recover by compacting or continuing rather than simply failing.

Task budget and token budget tracking

Claude Code distinguishes several resource concepts:

• model output limits
• turn output tokens
• task budget for the whole agentic turn
• token budgets that influence auto-continue behavior

This is another clue that the runtime is optimized for long, autonomous work rather than single-shot chat.

Tool-use summaries

The loop can create synthetic summaries of tool usage. That helps compress or preserve useful state without storing every raw detail in the active prompt window.

---

Message Model and Transcript Semantics

Claude Code uses a rich message model rather than just user and assistant strings.

You can see this in files such as:

• src/types/message.ts
• src/utils/messages.ts
• src/utils/sessionStorage.ts

Message categories include concepts like:

• user messages
• assistant messages
• system messages
• attachment messages
• progress messages
• tool summaries
• compact boundaries
• interruption-related messages

Why this matters

This is one of the most important lessons from the codebase.

If you want to build a serious agent tool, do not model the conversation as plain strings. You need structured message types that can represent:

• prompt input
• hidden system control messages
• tool requests and results
• temporary UI progress
• compaction boundaries
• resumable audit entries

Otherwise you will eventually lose correctness or resumability.

---

Tool System: The Heart of Claude Code

The tool system is centered around src/Tool.ts and src/tools.ts.

Tool.ts

This file defines the shared tool interfaces and tool use context.

The ToolUseContext is a particularly important abstraction. It carries:

• available commands
• available tools
• MCP clients and resources
• app state getters and setters
• abort controller
• read-file cache
• permission context
• notification methods
• prompt-request callbacks
• file history and attribution updaters
• streaming and UI control hooks
• query tracking metadata

This is the internal runtime contract that every tool depends on.

tools.ts

This file is the canonical tool registry.

It assembles the full tool list from:

• base built-in tools
• feature-gated tools
• ant-only tools
• worktree tools
• MCP resource tools
• testing or debug tools

Representative built-in tools include:

• AgentTool
• BashTool
• FileReadTool
• FileEditTool
• FileWriteTool
• NotebookEditTool
• GlobTool
• GrepTool
• WebFetchTool
• WebSearchTool
• AskUserQuestionTool
• TodoWriteTool
• ListMcpResourcesTool
• ReadMcpResourceTool
• SkillTool
• task and plan mode tools

Key design insight

The tool list is not hardcoded into a prompt only. It is a typed runtime registry with enablement rules and concurrency behavior. That is much stronger than an LLM wrapper that merely tells the model about tools in text.

---

Tool Orchestration and Concurrency

The execution logic is in src/services/tools/toolOrchestration.ts.

How tool execution works

When assistant output includes tool-use blocks:

1. Tool calls are partitioned into batches.
2. Each tool is checked for isConcurrencySafe.
3. Read-only or concurrency-safe batches can run concurrently.
4. Mutating or non-safe batches run serially.
5. Context modifiers from tool executions are applied in order.

This is a strong, pragmatic design.

It avoids two common failures in agent systems:

• fully serial execution that is too slow
• naive parallel execution that corrupts shared state

Why the partitioning matters

For example:

• multiple read/search operations can safely run together
• file edits generally should not run in parallel unless explicitly designed for it

This is exactly the kind of systems thinking required for real agent tools.

---

Commands Versus Tools

The command registry lives in src/commands.ts.

Commands

Commands are user-invoked, explicit control surfaces, usually slash commands.

Examples:

• /init
• /review
• /security-review
• /compact
• /memory
• /plugin
• /agents
• /tasks
• /teleport
• /branch
• /permissions

These commands are often lazy-loaded and may produce:

• a local UI action
• a prompt to the model
• a configuration flow
• a workflow setup experience

Tools

Tools are model-usable execution capabilities.

Examples:

• read a file
• edit a file
• run bash
• ask the user a question
• search the repo
• call an MCP resource or tool

The architectural split

This is one of the best design decisions in the codebase.

Commands are for deliberate user control. Tools are for model autonomy.

If you merge those concepts, your system becomes harder to reason about and harder to secure.

---

Permission Model and Safety Controls

The permission context is represented through shared types referenced by Tool.ts, app state, and permission utilities.

What the permission model does

Before a tool runs, the system can:

• allow automatically
• deny automatically
• ask the user
• apply source-based rules
• respect bypass or auto modes
• track denials

The tool permission context includes:

• mode
• additional working directories
• allow rules
• deny rules
• ask rules
• dangerous-rule stripping for auto mode
• flags for avoiding permission prompts in background contexts

Why it is structured this way

Claude Code is designed to run in many environments:

• fully interactive REPL sessions
• headless SDK calls
• remote bridge sessions
• subagents without direct UI access

A single boolean like allowTools would not be enough. The codebase instead treats permissions as context-aware policy.

This is the correct design for a serious agent platform.

---

Session Storage, History, and Resume

The most important persistence file is src/utils/sessionStorage.ts.

What gets persisted

Claude Code persists much more than plain conversation text.

It stores:

• transcript entries as JSONL
• compact boundary information
• content replacement metadata
• file history snapshots
• attribution snapshots
• worktree state
• subagent transcripts and metadata
• remote agent metadata

Why JSONL

JSONL is a good fit because:

• append-only writes are simple
• streaming writes are easy
• partial recovery is practical
• large sessions do not require rewriting one giant JSON blob each turn

Important implementation detail

The code distinguishes transcript messages from ephemeral progress messages. Progress messages are UI state, not durable conversation state.

That distinction is crucial. If you persist transient UI progress into the canonical conversation chain, resume logic becomes unreliable.

History versus transcript

There are multiple persistence concerns in this repository:

• command or prompt history for interactive convenience
• transcript storage for actual conversation recovery
• side stores for large pasted content
• file state snapshots for edit tracking

Those are separate concerns and the codebase treats them separately.

---

Context Management and Compaction

Claude Code has substantial machinery for long-context operation.

Relevant areas include:

• src/query.ts
• src/services/compact/
• src/services/contextCollapse/
• transcript storage code that records compaction boundaries

Why compaction is central

Agentic coding sessions can be very long and tool-heavy. If the system keeps every message verbatim forever, three things happen:

1. token cost explodes
2. latency increases
3. the model receives too much low-value detail

Claude Code solves this by making compaction a core runtime concern.

Architectural lesson

If you are building a similar tool, do not add summarization later as a patch. Design your transcript and turn loop with explicit compaction boundaries from day one.

---

MCP Integration

The MCP client logic lives in src/services/mcp/client.ts, with supporting types and config code under src/services/mcp/.

What Claude Code uses MCP for

MCP gives Claude Code a structured way to connect to external tool and resource providers.

Supported transport styles include:

• stdio
• SSE
• streamable HTTP
• WebSocket
• SDK control transport

What the client layer does

• connect to servers
• list tools
• list prompts
• list resources
• call tools
• handle auth failures
• handle session expiration
• manage OAuth-backed access where needed
• normalize server outputs and truncate or persist oversized content

Why this subsystem is notable

This is not a toy MCP integration. It includes:

• auth caching
• session expiration handling
• content truncation and persistence logic
• analytics and telemetry integration
• image resizing and output normalization

That means MCP is treated as a first-class production integration surface.

Practical architectural takeaway

If you want your tool to be extensible, an external tool protocol like MCP is a very strong design choice. It decouples your core runtime from the long tail of integrations.

---

Bridge and Remote Control

The bridge subsystem is centered on src/bridge/bridgeMain.ts and its neighboring files.

What bridge mode does

Bridge mode allows the local machine or environment to act as a remotely controlled Claude Code execution target.

What bridgeMain.ts reveals

This subsystem manages:

• environment registration
• session spawning
• polling for work
• heartbeat handling
• token refresh
• backoff and reconnect behavior
• session cleanup
• worktree creation and removal for isolated runs

Why it exists

Claude Code is not limited to a single terminal on a single machine. It is designed to support remote orchestration, web-connected sessions, and cloud-backed execution environments.

Architectural lesson

If you want to build something similar, keep the following separate:

• local user-facing UI runtime
• remote session supervisor
• session worker process
• authenticated control plane client

Claude Code follows that separation well.

---

Skills, Agents, and Plugins

This is one of the richest parts of the repository.

Skills

Skills are loaded primarily through markdown-based definitions, handled by src/skills/loadSkillsDir.ts.

A skill can contribute:

• a name
• description
• when-to-use guidance
• allowed tools
• optional hooks
• arguments
• execution context
• optional shell behavior
• model or effort hints

This is a lightweight way to package reusable workflows and domain knowledge.

Agents

Custom and built-in agents are handled through src/tools/AgentTool/loadAgentsDir.ts and the broader AgentTool subsystem.

Agent definitions can specify:

• prompt
• tool allowlists and disallowlists
• model and effort configuration
• permission mode
• MCP server requirements
• hooks
• background behavior
• isolation mode such as worktree or remote
• memory scope

This means an agent is treated as a configurable runtime persona with execution constraints, not just a different prompt.

Plugins

Plugins are handled by src/utils/plugins/pluginLoader.ts and related helpers.

A plugin can provide:

• commands
• agents
• hooks
• manifest metadata
• marketplace installation support

The loader handles:

• discovery
• validation
• caching
• version resolution
• seed directories
• source policy checks
• compatibility with marketplaces and git-based sources

Design lesson

Claude Code offers three extension levels:

• skills for lightweight reusable prompts and workflows
• agents for semi-autonomous specialized workers
• plugins for packaged, distributable extension bundles

That layering is excellent and worth copying.

---

Build and Packaging Story

build.mjs is especially useful because it shows how this extracted repo is meant to become a runnable JavaScript distribution.

What the build script does

• transpiles all src/ and vendor/ TypeScript into dist/
• preserves directory structure
• patches bun:bundle and bun:ffi imports with runtime shims
• rewrites src/... bare imports into relative paths for Node.js
• fixes .jsx imports after transpilation
• strips .d.ts runtime imports
• generates stub modules for missing internal references
• creates shims for internal packages

Why this is important

The build script confirms that the source tree is derived from a Bun-aware internal codebase, but adapted here for Node.js execution.

It also shows how heavily the codebase relies on build-time feature gating.

---

How Claude Code Works End-to-End

The easiest way to understand the whole system is to follow one interactive prompt.

End-to-end flow

1. The user launches claude.
2. cli.js loads src/entrypoints/cli.tsx.
3. The entrypoint checks for fast paths and special modes.
4. For the normal interactive path, main.tsx loads the main runtime.
5. init.ts initializes config, env, telemetry, proxy, trust-sensitive services, and cleanup.
6. setup.ts configures session-local state such as cwd, hooks, watchers, and worktree behavior.
7. The REPL launches via replLauncher.tsx.
8. The user types a prompt.
9. processUserInput.ts normalizes the input, handles slash commands or attachments, and invokes applicable hooks.
10. QueryEngine.submitMessage() prepares the session-level context.
11. query.ts sends a request to the model and starts streaming output.
12. If the model emits tool calls, toolOrchestration.ts executes them with concurrency rules and permission checks.
13. Tool results are appended to the message stream and may cause the loop to continue.
14. Session state and transcript entries are persisted through sessionStorage.ts.
15. The UI re-renders continuously from shared application state.
16. If the context grows too large, compaction logic summarizes or collapses history.
17. The turn ends when the model returns a terminal answer or the loop hits a budget, recovery, or interruption boundary.

The core mental model

Claude Code is a stateful event-driven agent runtime wrapped in a terminal UI.

That is the right way to think about it.

It is not merely:

• a REPL
• a prompt template
• a shell wrapper
• a tool-calling demo

It is closer to an operating environment for a coding agent.

---

Why the Architecture Looks the Way It Does

Several recurring design pressures explain the structure of the codebase.

1. Long-lived sessions

Because coding sessions can last a long time, the system needs:

• durable transcripts
• compaction
• file state snapshots
• resumability

2. Mixed determinism and autonomy

Because some actions must be explicit and some can be agentic, the system has both:

• commands for deterministic user control
• tools for model autonomy

3. Security and policy constraints

Because the product can edit files and run shell commands, it needs:

• permission rules
• policy limits
• trust-gated initialization
• sandbox and remote-control awareness

4. Extensibility

Because users want custom workflows, the system supports:

• skills
• agents
• plugins
• MCP servers

5. Deployment diversity

Because the same codebase runs in local terminals, remote environments, background daemons, and internal workflows, the architecture is highly feature-gated and modular.

---

Strengths of the Codebase

From an engineering perspective, several things are especially strong.

Strong separation between session state and turn execution

QueryEngine.ts versus query.ts is a good split.

Real persistence model

The transcript system is serious and production-minded.

Mature tool context abstraction

ToolUseContext carries the right kind of shared runtime contract.

Extensibility layering

Skills, agents, plugins, and MCP are distinct but composable.

Thoughtful concurrency

Tool orchestration does not blindly serialize everything or parallelize everything.

Startup performance awareness

The codebase clearly optimizes startup and module loading.

---

Complexity Costs and Tradeoffs

The codebase is strong, but it is also complex.

main.tsx is extremely dense

It acts as a high-gravity orchestration module. That is understandable for a CLI entrypoint, but it also means many features converge there.

Feature-gated branches make global reasoning harder

The heavy use of feature(...) is operationally useful, but it makes static comprehension harder.

Rich shared state is powerful but expensive

A broad app state object helps feature composition, but also increases coupling between systems.

Many layers interact through side effects

For example: config, env vars, managed settings, telemetry, policy limits, and auth can influence one another during startup.

These are normal tradeoffs for a mature agent runtime, not signs of bad engineering.

---

Implementation Guide: How to Build a Similar Tool

This section distills the architectural lessons from Claude Code into a practical blueprint.

Principle 1: Build a runtime, not a wrapper

Do not start with the mindset of "I need a CLI that calls an LLM".

Start with this mindset instead:

"I am building a runtime that manages sessions, tools, policy, persistence, and context for an agent."

That framing changes the design in the right way.

Principle 2: Split the system into these core modules

If you are implementing a similar tool, aim for these subsystems from the beginning:

1. CLI bootstrap
2. global initialization
3. session manager
4. turn executor
5. tool registry
6. permission engine
7. transcript store
8. UI layer
9. integration layer
10. extension layer

Suggested architecture for a new implementation

A. Bootstrap layer

Responsibilities:

• parse CLI flags
• dispatch into runtime modes
• keep fast paths cheap
• load heavy modules lazily

Recommended pattern:

• one tiny root executable
• one dynamic-import dispatcher
• one main application entrypoint

B. Global initialization layer

Responsibilities:

• config loading
• environment setup
• telemetry init
• trust and policy loading
• proxy and network configuration
• cleanup registration

Recommendation:

Separate global process init from session init.

C. Session object

Create a SessionRuntime or QueryEngine equivalent that owns:

• message history
• usage counters
• active config snapshot
• cancellation
• caches
• permission history
• resumable state

This object should survive across multiple turns.

D. Turn executor

Implement a pure-ish turn loop that:

• takes normalized messages and a tool context
• calls the model
• streams output
• executes tool calls
• manages continuation and compaction
• returns terminal status

Recommendation:

Keep this separate from the session object so it is testable.

E. Structured message model

Do not use plain strings as your canonical transcript representation.

You need message variants for at least:

• user input
• assistant output
• system notices
• tool calls
• tool results
• hidden control messages
• attachments
• progress events
• compaction markers

F. Tool system

Model every tool with:

• name
• schema
• execution method
• concurrency safety signal
• optional permission classification
• optional output-shaping rules

Also create a shared ToolContext with:

• app state access
• filesystem access
• network clients
• cancellation
• permission helpers
• notification hooks
• transcript appenders

G. Permission engine

Do not bolt security on later.

Build a permission engine that can answer:

• is this tool allowed?
• does this input change risk level?
• can this context prompt the user?
• should this background worker auto-deny?

H. Transcript and resume system

Use append-only JSONL or event-sourcing.

Persist:

• messages
• tool boundaries
• compaction boundaries
• file edit snapshots
• resumable metadata

Design resumption before you ship, not after.

I. Compaction from day one

Design your transcript format so you can summarize old segments while preserving continuity.

At minimum, store:

• a boundary marker
• the summary content
• enough metadata to reconstruct what was compacted

J. Extensibility model

Copy Claude Code's layered approach:

• skills for reusable prompt workflows
• agents for specialized autonomous workers
• plugins for packaged extensions
• MCP or equivalent for external integrations

This is much better than one monolithic plugin abstraction.

---

Suggested Implementation Roadmap

If you were building a similar tool from scratch, a sensible sequence would be:

Phase 1: Basic interactive runtime

Build:

• CLI bootstrap
• session object
• turn executor
• simple REPL
• transcript logging

Avoid at this phase:

• plugins
• multi-agent orchestration
• remote control

Phase 2: Core tools and permissions

Add:

• file read and edit tools
• shell execution tool
• repo search tools
• permission prompts and rule engine

Phase 3: Context durability

Add:

• transcript resume
• file history snapshots
• compaction and summarization
• usage and budget tracking

Phase 4: Extensibility

Add:

• skills from markdown
• plugin packages
• custom agents
• MCP client support

Phase 5: advanced operational modes

Add:

• background sessions
• remote bridge mode
• worktree isolation
• multi-agent task orchestration

This sequencing mirrors the natural dependency order in the Claude Code architecture.

---

What to Copy Directly From Claude Code's Design

If you are implementing a similar product, these ideas are especially worth reusing.

Copy these concepts

• session object plus separate turn loop
• typed ToolUseContext
• append-only JSONL transcripts
• explicit compaction boundaries
• separate commands and tools
• concurrency-safe versus mutating tool partitioning
• markdown-based skills
• agent definitions with tool and permission constraints
• external integration protocol like MCP
• dynamic-import bootstrap with cheap fast paths

Be careful copying these concepts

• a single enormous main entrypoint
• excessive feature-gated branching without strong module boundaries
• too much mutable cross-cutting app state unless you truly need it

---

If You Want to Study One Thing Most Closely

The most instructive trio in the whole repository is:

1. src/QueryEngine.ts
2. src/query.ts
3. src/Tool.ts

Those files capture the central idea of Claude Code:

• maintain durable session state
• execute one turn as a streaming loop
• expose capabilities through a strongly typed tool runtime

Everything else is either supporting infrastructure, UI, persistence, or extension on top of that core.

---

Final Takeaway

Claude Code works because it treats coding assistance as a systems problem, not only as a prompting problem.

Its core architecture combines:

• a session-oriented runtime
• a streaming agent loop
• typed tools with permissions
• durable transcripts and compaction
• a rich terminal UI
• layered extensibility
• remote and local execution modes

If you want to build a similar tool, that is the real lesson from this codebase.

Do not start with the prompt. Start with the runtime.