Claude Code Agent Harness Structure

[!NOTE] This walkthrough is based on a local source snapshot under claw-code, analyzed on April 1, 2026 with the major help of Codex. It is not an official architecture document. I am working on the full runtime diagram and a lightweight CLI.

I know the leaks from Claude Code from X a little bit late, so when I head to the Reddit and GitHub, the first forked repo was already unavailable. But I still got many other useful sources and somehow many other genius geekers have already wrapped the key features of this grail into something new. As someone who wants to know about the latest developments in AI Agent harnessing engineering, I have no intest on making money on this, but rather love to dig into it a little bit. So here we are. But honestly, majorities of the analysis and reviews were done by Codex, what I did was merely checking the key points, picking something I felt is interesting. Shout out to Codex, my pal, you do save my time.

Here are some useful resources before I get started:

A blog by Alex Kim talking about the Claude Code Source Leak: The Claude Code Source Leak: fake tools, frustration regexes, undercover mode, and more
My reference repo, a guy turned the leak code into Python and now is working on the Rust version: claw-code
A really awesome architecture diagram of Claude Code Agent Runtime by Wayland Zhang: Claude Code Diagram
- Another project from Wayland: Shannon - A multi-tenant platform built on Temporal workflows, with Rust enforcement and Firecracker isolation.

Claude Code’s terminal runtime stands out because it is not built like a thin CLI wrapper around a model API. It behaves much more like an agent harness platform: a long-lived session runtime with explicit tool protocols, permission races, background tasks, remote execution, transcript persistence, and multiple extension layers that all meet in the same query loop.

What feels especially strong in this codebase is the amount of runtime engineering that has been pulled into first-class subsystems instead of being left as hidden glue:

Boot is optimized like an application startup path, not a script entrypoint. main.tsx starts MDM and keychain prefetch immediately, then continues loading the runtime in parallel.
The query/tool loop is shared infrastructure across interactive REPL, headless printing, remote control, and remote sessions, instead of separate product-specific paths.
Permissions are treated as a multi-source control problem. User approval, hooks, bridge replies, channels, and classifiers are all explicit resolution paths.
State persistence is central, not optional. Transcript JSONL, task sidecars, file history, compaction boundaries, and recovery code make long sessions resumable.
Feature layers are deeply integrated but still shippable through build-time feature gates and runtime experiments. BUDDY, KAIROS, ULTRAPLAN, coordinator mode, cron triggers, bridge mode, and MCP all slot into the same harness.

Simple Roadmap

CLI bootstrap main.tsx, setup.ts, entrypoints/, bootstrap/state.ts
Interactive surfaces screens/REPL.tsx, cli/print.ts, interactiveHelpers.tsx, replLauncher.tsx
Conversation engine QueryEngine.ts, query.ts, services/compact/*, context.ts
Tool and permission runtime tools.ts, Tool.ts, services/tools/*, hooks/toolPermission/*, utils/permissions/*
Agent/task orchestration tasks/*, tools/AgentTool/*, coordinator/coordinatorMode.ts
Extension layers services/mcp/*, skills/*, utils/plugins/*, commands/*
Remote and bridge execution bridge/*, commands/ultraplan.tsx, utils/ultraplan/*, remote/*
Persistence and recovery utils/sessionStorage.ts, utils/conversationRecovery.ts, history.ts, memdir/*

The interactive explorer below is meant to make that structure inspectable. Start from the overview graph, click into a subsystem or file, and then pivot through imports, reverse imports, and neighboring directories.

Snapshot

1884 Source files

283 Directories

514548 Lines of code

utils Largest subsystem

Biggest Subsystems

utils · 181036 lines
components · 81935 lines
commands · 26617 lines
tools · 51012 lines
services · 53810 lines
hooks · 19308 lines

Heavyweight Files

cli/print.ts · 5595 lines
utils/messages.ts · 5513 lines
utils/sessionStorage.ts · 5106 lines
utils/hooks.ts · 5023 lines
screens/REPL.tsx · 5006 lines
main.tsx · 4684 lines

Feature Gates That Pop Up Most

KAIROS · 57 files feature('KAIROS')
TRANSCRIPT_CLASSIFIER · 44 files feature('TRANSCRIPT_CLASSIFIER')
KAIROS_BRIEF · 20 files feature('KAIROS_BRIEF')
BASH_CLASSIFIER · 19 files feature('BASH_CLASSIFIER')
TEAMMEM · 17 files feature('TEAMMEM')
COORDINATOR_MODE · 15 files feature('COORDINATOR_MODE')
PROACTIVE · 15 files feature('PROACTIVE')
VOICE_MODE · 14 files feature('VOICE_MODE')

Interactive Architecture Explorer

Start from the runtime overview, then click into a directory or file to unfold its neighborhood. The diagram is rendered with Mermaid, but the data comes from the actual `src/` tree and import graph.

Tip: use search to jump straight to `QueryEngine.ts`, `bridge/replBridge.ts`, `toolExecution.ts`, or `commands/ultraplan.tsx`.

Loading architecture data…

Key Feature Cards

Query Loop

The core turn engine. Messages enter here, tools are detected here, compaction and retries are triggered here, and the loop decides whether another model round is needed.

src/query.ts

src/QueryEngine.ts

src/services/compact/compact.ts

src/services/tools/StreamingToolExecutor.ts

Tool Runtime

Claude Code treats tools as a runtime, not just function calls. The registry, orchestration, execution, telemetry, and result-shaping layers are all explicit.

src/tools.ts

src/Tool.ts

src/services/tools/toolExecution.ts

src/services/tools/toolOrchestration.ts

Permission Engine

Permission decisions can come from the user, hooks, bridge clients, channels, or classifiers. The harness resolves those races carefully instead of assuming one approval path.

src/hooks/toolPermission/PermissionContext.ts

src/hooks/toolPermission/handlers/interactiveHandler.ts

src/utils/permissions/permissions.ts

Tasks And Agents

Worker agents, bash jobs, remote sessions, and long-running background work all map onto a shared task model with disk-backed output and resumable metadata.

src/tasks/LocalAgentTask/LocalAgentTask.tsx

src/tasks/RemoteAgentTask/RemoteAgentTask.tsx

src/coordinator/coordinatorMode.ts

MCP, Plugins, Skills

The harness is built like a platform. MCP servers, plugin bundles, and markdown skills expand capability without needing to fork the core query loop.

src/services/mcp/client.ts

src/services/mcp/MCPConnectionManager.tsx

src/utils/plugins/pluginLoader.ts

src/skills/bundled/index.ts

Bridge And Remote

The same runtime ideas power IDE bridge mode, remote control, and browser-linked sessions. That lets the terminal, IDE, and web flows share the same message and tool machinery.

src/bridge/bridgeMain.ts

src/bridge/replBridge.ts

src/bridge/initReplBridge.ts

BUDDY

BUDDY is not just decorative UI. It has its own sprite system, deterministic identity generation, prompt attachments, and placement logic inside the REPL.

src/buddy/CompanionSprite.tsx

src/buddy/companion.ts

src/buddy/prompt.ts

KAIROS

KAIROS behaves like a resident assistant layer: bridge continuity, scheduled prompts, brief mode, and longer-lived assistant behavior gated into the same harness.

src/tools/ScheduleCronTool/prompt.ts

src/assistant/sessionHistory.ts

src/bridge/initReplBridge.ts

ULTRAPLAN

ULTRAPLAN shows how the runtime stretches beyond the terminal: launch a remote plan session, monitor it locally, and either teleport the plan back or keep execution in the browser.

src/commands/ultraplan.tsx

src/utils/ultraplan/ccrSession.ts

src/tasks/RemoteAgentTask/RemoteAgentTask.tsx