deep dive · claude code · part 1 — the overview

Claude Code is a CLI. You type a prompt, it does some stuff on your machine, and it replies. What happens between those two moments — the "some stuff" — is almost 1900 TypeScript files. That's a lot of files to sit between a keystroke and an API call.

This series is me trying to understand all of it, piece by piece. This first post is the overview: what's in the source tree, what's load-bearing, what's scaffolding, and the single shape that makes sense of the whole thing. The deep dives come after.

agent, not chat client

From the outside it's a pipe: prompt in, API request out, response back, text in the terminal. What makes it an agent rather than a chat client is the middle — between your prompt and the model's final reply, Claude Code will often run things on your machine on the model's behalf (read files, execute shell commands, search the web, call MCP servers) and fold each result back into the conversation before calling the model again. So the CLI is really a three-way mediator: user ↔ Claude Code ↔ (Claude API, local system), and everything in src/ exists to serve that mediation.

opening the box · by file count

Before I looked at the source I assumed it'd be organized around "agent brain" concerns: a big prompt-engineering module, a big conversation manager, maybe a policy engine. It's not — or at least, not visibly. Here's the top-level src/ folder sorted by raw .ts/.tsx file count:

click any folder to see its sub-directories.

That's a shock the first time you see it. utils/ — the grab-bag folder — is the biggest, with 564 files of paths, fs helpers, ANSI conversion, auth plumbing, perf tracing, and dozens of other one-off helpers. components/ is the second biggest, and it's almost entirely React/Ink UI. The next four — commands, tools, services, hooks — are mostly wiring: slash commands, tool implementations, service clients, React hooks for the REPL.

At the root of src/ there are only 18 non-directory files. Most of them are small. But three of them — query.ts (1729 lines), QueryEngine.ts (1295), and Tool.ts (792) — contain the entire agent. I've highlighted them in green above. About 3800 lines run the show; the other ~200,000 are scaffolding around them — UI chrome, slash commands, plugin loading, permissions, MCP wrapping, IDE integration. Real work, but not the work you'd sketch on a whiteboard.

the shape · one envelope, one loop

Here's the useful mental model I eventually landed on:

Claude Code is a function that builds one envelope and runs one loop.

The envelope is an API request. It has three slots: system, tools, messages. Every turn — every single time the model is called — that envelope is rebuilt from scratch by gathering data from all over the source tree. Claude Code doesn't keep state on the API side; there are no server-side threads or assistants. Each call sends the entire envelope, and each call reassembles it.

The loop is what happens around the envelope. You send it, the model responds, and the response either contains tool calls or it doesn't. If it doesn't, the loop exits — the model is done talking. If it does, Claude Code executes each tool (reads in parallel, writes serially), collects the results, appends them to messages, and loops back to send a new envelope. This keeps going until the model stops asking for tools, hits a turn limit, or the user aborts.

The animation below walks one full turn through that pipe — envelope assembly, the API call, tool execution, a loop-back to rebuild, and the final streamed text.

what goes in the envelope

Each slot is fed by code from multiple folders. Once you know who feeds what, the tree stops feeling arbitrary.

system — the system prompt — is assembled from:

• constants/prompts.ts — 914 lines of fixed prompt text: intro, tool-use rules, safety notes, task guidance.
• constants/systemPromptSections.ts — section templates that plug dynamic data into the fixed prompt.
• context.ts — the user's CLAUDE.md files (global + project + local), current date, git branch and recent commits.
• services/mcp/ — any instructions field advertised by connected MCP servers gets appended.
• skills/ — the currently loaded skills' names and descriptions.
• constants/outputStyles.ts — the selected output style overlay.
• setup.ts and utils/ — the OS/platform environment block.

tools — the tool declarations — come from:

• tools.ts — the tool registry, ~160 tools, lazy-loaded and feature-gated.
• tools/*/ — 42 tool directories, each exporting a name, a description, and a Zod inputSchema.
• services/mcp/ — any MCP-exposed tools, wrapped so the model sees them uniformly with the native ones.
• Several tools are conditionally included via build-time macros (feature('KAIROS'), feature('BRIDGE_MODE')) or USER_TYPE === 'ant'. They simply don't exist in external builds — dead-code-eliminated at bundle time.

messages — the conversation history — comes from:

• The in-memory Message[] held in AppStateStore.
• services/compact/, which may have already inserted a summary and a compact-boundary marker at the top of the list.
• history.ts — the session transcript writer, which also feeds message restoration on /resume.
• On every turn, the pre-query pipeline may trim or rewrite this list: micro-compaction, tool-result budget trimming, snipping very old pairs, context collapse, and full auto-compaction if tokens exceed the budget.

The fact that these sources are so scattered across the tree is exactly why a holistic picture matters before a deep dive. The prompt isn't written in one place. It's gathered.

Here's what the envelope actually looks like for a realistic prompt, picked up mid-session so you can see prior history flow into the rebuild. Each step applies one diff — new content flashes amber.

(empty)

(empty)

(empty)

the loop

With the envelope built, the loop itself lives in query.ts. It's an async function* — an AsyncGenerator — so it can yield messages as they arrive and let the REPL stream tokens to the terminal in real time. Stripped of hooks, error recovery, and bookkeeping, the shape is:

async function* query(state) {
  while (true) {
    // 1. rebuild the envelope, apply compaction layers
    const envelope = prepareEnvelope(state)

    // 2. stream the API call
    const response = yield* queryModelWithStreaming(envelope)

    // 3. done if the model didn't ask for tools
    if (!response.hasToolCalls) return

    // 4. execute tools (reads parallel, writes serial)
    const results = yield* runTools(response.toolCalls)

    // 5. append results, loop
    state.messages.push(...results)
  }
}

The real query.ts adds layers around each step: pre- and post-tool hooks, post-sampling hooks, stop hooks that can veto continuation, reactive compaction on prompt_too_long errors, max-turn limits, and an abort-signal tree that lets ctrl-c unwind the pipeline cleanly. But the skeleton is what it is: prepare → call → execute → repeat.

zooming out · harness engineering

There's a name for what we just walked through: harness engineering. Agent = model + harness. The model is the stateless API endpoint. The harness is everything else — the loop, the tool registry, the permission gates, the compaction, the hooks, the session store. It's what turns a raw LLM into something you can trust with a keyboard.

Claude Code is one of the most polished production harnesses in the wild, and it's unusual in that Anthropic ships the same binary they use internally — it's the real thing, not a demo. The 3800-vs-200K line split from earlier now has a proper name: the 3800 lines are the agentic core, the 200K are the harness around them. This series reads that harness one subsystem at a time.

more to come — each of those subsystems is a post of its own.