Claude Code: Source Reading Series

How cli.tsx, main.tsx, and replLauncher.tsx assemble a governed agent session — from startup signal handlers to first REPL render. Includes the T+0/2/137/150ms startup timeline and side-effect hoisting.

src/
├── cli.tsx
├── main.tsx
├── entrypoints/
│   └── init.ts
├── setup.ts
└── replLauncher.tsx

How processUserInput routes text / !bash / /slash into three separate paths, how speculative execution preemptively forks a turn before the user submits, and how prompt suggestions are generated as a background latency optimization.

src/
└── utils/
    ├── processUserInput/
    │   └── processUserInput.ts
    ├── speculation/
    │   └── speculativeExecute.ts
    └── promptSuggestion

How query.ts manages the full turn lifecycle as a recoverable AsyncGenerator with seven named recovery conditions, a five-step preprocessing pipeline, and streaming-aware tool execution.

src/
├── query.ts
├── query/
│   ├── config.ts
│   ├── tokenBudget.ts
│   └── stopHooks.ts
└── services/
    └── compact/
        ├── autoCompact.ts
        ├── microCompact.ts
        └── contextCollapse.ts

How six source types — built-in, user skills, plugin-injected, project-scoped, MCP-derived, and dynamic — assemble into a memoized command registry that is re-filtered at call time by availability requirements.

src/
└── commands.ts

The 20+ property Tool interface, buildTool() fail-closed defaults, and how 25+ built-in tools are organized into seven categories and assembled per session.

src/
├── Tool.ts
└── tools.ts

How partitionToolCalls schedules concurrent vs serial batches, how StreamingToolExecutor starts tools before the model finishes streaming, and how the tombstone/discard pattern handles fallback cleanup.

src/
└── services/
    └── tools/
        ├── toolOrchestration.ts
        ├── toolExecution.ts
        └── StreamingToolExecutor.ts

The 7-step permission decision tree with bypass-immune safety gates, AI Classifier for auto-mode, and how the sandbox layer wraps @anthropic-ai/sandbox-runtime as a separate execution isolation system.

src/
├── utils/
│   └── permissions/
│       ├── permissions.ts
│       └── permissionSetup.ts
└── hooks/
    ├── useCanUseTool.tsx
    └── toolPermission/
        └── handlers/
            ├── autoHandler.ts
            └── interactiveHandler.ts

How MCP server definitions from seven config sources are deduplicated by content signature, connected, then expanded into runtime-visible Tool objects, Command objects, and Resource entries.

src/
└── services/
    └── mcp/
        ├── config.ts
        ├── client.ts
        └── ChromeMcpClient.ts

Multi-server LSP stack with a 5-state lifecycle, LRU-bounded diagnostic registry (10 per file / 30 total), and push-based passive diagnostic collection that avoids flooding the model with repeated errors.

src/
└── services/
    └── lsp/
        ├── LSPServerInstance.ts
        └── LSPDiagnosticRegistry.ts

Five-layer memory architecture: memdir CLAUDE.md management, Relevant Memories per-turn selector (5th layer), SessionMemory within-session notes, ExtractMemories episodic capture with 4-type taxonomy, and AutoDream background consolidation with 5-gate access control.

src/
├── utils/
│   └── memdir.ts
└── services/
    ├── relevantMemories/
    │   └── relevantMemories.ts
    ├── SessionMemory/
    │   └── SessionMemory.ts
    ├── extractMemories/
    │   └── extractMemories.ts
    └── autoDream/
        └── autoDream.ts

Five task types (shell, local_agent, remote_agent, local_main_session, dream), how LocalMainSessionTask backgrounds the main query loop itself, and the lifecycle/observation/cancellation contract every task satisfies.

src/
├── Task.ts
├── tasks.ts
└── tasks/
    └── DreamTask/
        └── DreamTask.ts

How runAgent materializes a child agent turn with its own ToolUseContext, why setAppState is a no-op in async subagents while setAppStateForTasks always reaches the root store, and how fork mode preserves prompt cache coherence.

src/
├── tools/
│   └── AgentTool/
│       ├── runAgent.ts
│       └── AgentTool.tsx
└── tasks/
    └── RemoteAgentTask/
        └── RemoteAgentTask.tsx

How coordinatorMode implements a synthesize-first delegation strategy, three swarm backends (TmuxBackend binary tree / ITermBackend / InProcessBackend), and how disjoint file ownership prevents agent interference.

src/
├── coordinator/
│   └── coordinatorMode.ts
└── utils/
    └── swarm/
        └── backends/
            ├── TmuxBackend.ts
            ├── ITermBackend.ts
            └── InProcessBackend.ts

AppStateStore (75+ fields, DeepImmutable<T>) as a session control plane, useSyncExternalStore selectors for re-render control, and the custom Ink frame pipeline (reconcile → Yoga layout → screen buffer → diff → patch).

src/
├── state/
│   ├── AppStateStore.ts
│   └── Store.ts
└── ink/
    └── ink.tsx

Dual-sink event emission (Datadog + first-party BQ), never-type PII enforcement at compile time, OTEL spans instrumented across the full turn via AsyncLocalStorage, and beta session tracing with system-reminder extraction.

src/
├── services/
│   └── analytics/
│       └── index.ts
└── utils/
    └── telemetry/
        ├── otel.ts
        └── betaSessionTracing.ts

REPL.tsx at 5005 lines as the composition root mounting 30+ hooks, the QueryGuard state machine preventing race conditions, stale-read discipline via store.getState(), and the overlay priority stack.

src/
└── screens/
    └── REPL.tsx

The five cross-cutting principles that unify the full series: capability assembly, recoverable turn loops, tool execution as a governed subsystem, state as a control plane, and detached work as first-class runtime.

src/
├── cli.tsx
├── main.tsx
├── query.ts
├── tools.ts
├── state/
│   └── AppStateStore.ts
├── tasks
└── tools/
    └── AgentTool

BashTool five defense layers (tree-sitter AST, read-only validation, path validation, destructive warnings, sandbox routing), FileReadTool device blocking, AgentTool nesting depth limit, and autoCompact circuit breaker.

src/
└── tools/
    ├── BashTool/
    │   ├── BashTool.tsx
    │   ├── bashPermissions.ts
    │   └── readOnlyValidation.ts
    ├── FileEditTool/
    │   └── FileEditTool.ts
    └── FileReadTool/
        └── FileReadTool.ts