Decompiled TypeScript source (~512K LOC) of Anthropic's Claude Code v2.1.88. AsyncGenerator agent loop (QueryEngine→query()→StreamingToolExecutor) with 40+ tools, React/Ink TUI, 4-tier permission engine, 3-strategy context compaction, 5-mode sub-agent spawning, and 108 dead-code-eliminated internal modules.
| Field | Value |
|---|---|
| Repo | |
| Upstream | sanbuphy/learn-coding-agent (11,910 stars, 19,728 forks) |
| Primary language | TypeScript (30.3M bytes), JavaScript (27K bytes) |
| LOC | ~512,664 across ~1,884 .ts/.tsx files |
| Largest single file | query.ts (~785KB) |
| License | None specified (Anthropic copyright disclaimer) |
| Version analyzed | 2.1.88 (extracted from npm @anthropic-ai/claude-code) |
| Runtime | Bun-compiled → Node.js ≥ 18 (12MB self-contained bundle) |
| Stars | 0 (fork); upstream: 11,910 |
| Date | 2026-03 |
One-line pitch: Production-grade agentic coding assistant that wraps a while-true tool-use loop with permissions, streaming, context compression, multi-agent orchestration, and terminal UI.
The canonical LLM agent pattern — call the model, check for tool_use stop reason, execute tools, append results, loop — breaks down at production scale for several compounding reasons. (1) Unrestricted tool execution on a user's filesystem is a security catastrophe; every tool call needs permission gating with rules, user prompts, and sandboxing. (2) Multi-turn conversations exceed context windows within minutes of real coding work; without compression, the model loses coherent context or the API rejects the request. (3) Complex tasks require decomposition into sub-agents, each needing isolated context to avoid cross-contamination, but sharing file state for coherent edits. (4) Users interact via multiple surfaces — interactive CLI, headless SDK, remote bridge from Claude Desktop — requiring a shared core engine with pluggable I/O. (5) The tool set itself must be extensible (MCP protocol, user plugins, skills) without modifying core loop logic.
The architecture factors the agent loop into QueryEngine.submitMessage() which yields SDKMessage via an AsyncGenerator. This generator delegates to query() (the inner while-true loop calling Claude API), which dispatches tool calls through StreamingToolExecutor. Around this core loop, 12 progressive harness mechanisms layer on production concerns:
query.ts): while-true calling Claude API, checking stop_reason, executing toolsTool.ts + tools.ts): buildTool() factory with validateInput→checkPermissions→call lifecycleEnterPlanModeTool + TodoWriteTool): list steps before executingAgentTool + forkSubagent.ts): child agents with fresh messages[] but shared file cacheSkillTool + memdir/): inject context via tool_result, not system prompt; CLAUDE.md lazy loadingservices/compact/): autoCompact + snipCompact + contextCollapseTaskCreate/Update/Get/List): file-based task graph with status trackingDreamTask + LocalShellTask): daemon threads with completion notificationsTeamCreate/Delete + InProcessTeammateTask): persistent teammates with async mailboxesSendMessageTool): one request-response pattern for all agent negotiationcoordinator/coordinatorMode.ts): idle cycle + auto-claimEnterWorktreeTool): tasks manage goals, worktrees manage directoriesThe permission system enforces a 4-stage pipeline: validateInput() → PreToolUse hooks (user-defined shell scripts) → permission rules (alwaysAllow / alwaysDeny / alwaysAsk from settings, CLI args, session decisions) → interactive prompt (allow once / always / deny) → checkPermissions() (tool-specific path sandboxing) → tool execution.
The AsyncGenerator-based agent loop design. By making submitMessage() return AsyncGenerator, the engine achieves full-chain streaming from API through tool execution to consumer — every intermediate result (partial text, tool progress, stream events, usage accounting) is yielded as it arrives, not buffered. This single design choice enables three critical properties simultaneously: (a) SDK consumers get real-time streaming without callbacks, (b) the REPL and bridge surfaces compose the same generator with different rendering, and (c) cancellation propagates naturally via AbortController without explicit cleanup at each layer. The alternative — callback-based or observable-based streaming — would require explicit subscription management and error propagation at every intermediate layer, which at 40+ tools and 12 harness mechanisms would be a maintenance disaster.
Ships as Anthropic's primary coding CLI. The decompiled source reveals 108 feature-gated modules not present in the published build (daemon, multi-agent coordinator, voice mode, KAIROS autonomous agent, browser automation) — indicating the shipped product exposes roughly 40% of the implemented capability surface. The 12-mechanism harness architecture has proven sufficient to support interactive REPL, headless SDK, remote bridge, and multi-agent swarm modes from a single codebase.
Top modules by centrality:
| Module | Purpose |
|---|---|
src/query.ts (~785KB) | The agent loop: while-true calling Claude API, checking stop_reason, executing tools, managing turns |
src/QueryEngine.ts | Query lifecycle + session state; submitMessage() → AsyncGenerator |
src/Tool.ts | Tool interface definition + buildTool() factory with safe defaults |
src/tools.ts | Tool registry, presets, filtering — what tools are available per context |
src/main.tsx (4,683 LOC) | REPL bootstrap: interactive terminal entry point |
src/bridge/bridgeMain.ts (115KB) | Claude Desktop / remote session lifecycle manager |
src/cli/print.ts (212KB) | Output rendering engine for terminal display |
src/services/tools/ | StreamingToolExecutor + toolOrchestration — concurrent tool dispatch |
src/services/compact/ | Context compression: autoCompact, snipCompact, contextCollapse |
src/utils/permissions/ | Permission rule engine: allow/deny/ask rules with glob matching |
src/commands.ts | Slash command definitions (~80+ commands) with feature-gated imports |
src/bootstrap/state.ts (56KB) | Bootstrap state: session ID, persistence, environment config |
| Entry | Path | Role |
|---|---|---|
| CLI | src/entrypoints/cli.tsx | Version, help, daemon launch — primary user-facing entry |
| REPL | src/main.tsx | Interactive terminal session (4,683 LOC bootstrap) |
| SDK | src/entrypoints/sdk/ | Headless/programmatic API via QueryEngine |
| MCP Server | src/entrypoints/mcp.ts | Expose Claude Code as an MCP server |
| Bridge | src/bridge/bridgeMain.ts | Claude Desktop remote session manager |
QueryEngine) #The headless API is a single class with one primary method:
new QueryEngine(config: QueryEngineConfig) — accepts tools, commands, MCP clients, agent definitions, permission handler, app state, model config, budget limitsengine.submitMessage(prompt, options?) → AsyncGenerator — yields streaming messages (assistant text, tool use, progress, stream events, result with cost/usage/session_id)| Mechanism | Examples | Source |
|---|---|---|
| CLI flags | --continue, --resume , --fork-session, --model, --max-turns | cli.tsx arg parsing |
| Environment vars | USER_TYPE=ant (internal mode), CLAUDE_CODE_* family | config.ts, bootstrap/state.ts |
| Settings files | .claude/settings.json, .claude/settings.local.json | utils/settings/ |
| CLAUDE.md | Project-level memory files (lazy-loaded) | memdir/memdir.ts |
| Feature flags | GrowthBook runtime flags (A/B experiments) | services/analytics/ |
| Compile-time flags | feature() from Bun — KAIROS, DAEMON, VOICE_MODE, etc. | scripts/transform.mjs |
| Permission rules | alwaysAllow, alwaysDeny, alwaysAsk per tool + glob pattern | utils/permissions/ |
| Slash commands | 80+ commands (/compact, /plan, /resume, /review, /mcp, etc.) | src/commands/ |
| MCP config | stdio/sse/http/ws/sdk transports, OAuth 2.0, API key auth | services/mcp/ |
| Hooks | PreToolUse / PostToolUse user-defined shell scripts | utils/hooks/ |
buildTool() factory — any new tool implements the Tool interface (validate, check permissions, call, render)MCPConnectionManager dynamically discovers and registers external tools via mcp____ namingservices/plugins/ + commands/plugins.ts — runtime-loadable plugin systemskills/loadSkillsDir.ts — directory-based skill discovery, injected via tool_resultcli/transports/ — SSE, WebSocket, Hybrid, ccrClient for I/OMessage — Discriminated Union (src/types/message.ts) #type field: assistant (model output with content blocks), user (user input or tool results), system (system prompt parts), stream_event (SSE events), attachment (structured output, max_turns), progress (tool execution progress).processUserInput(), assistant messages yielded by query(), both accumulated in QueryEngine.mutableMessages[]. Persisted to session JSONL on creation.Tool — Generic Interface (src/Tool.ts) #z.ZodType), output type, and progress data. ~30 methods spanning lifecycle (validateInput, checkPermissions, call), capability queries (isEnabled, isConcurrencySafe, isReadOnly, isDestructive), rendering (renderToolUseMessage, renderToolResultMessage — React/Ink nodes), and AI-facing description.tools.ts, filtered per context (feature flags, permissions, MCP discovery). Tool instances are stateless — all mutable state lives in ToolUseContext.buildTool() construction. State flows through ToolUseContext parameter.ToolUseContext — Execution Environment (src/Tool.ts) #query() invocation, threaded through all tool calls within a turn.messages, updating readFileState, adding to discoveredSkillNames).TaskStateBase — Task Tracking (src/Task.ts) #id (prefixed: b=bash, a=agent, r=remote, t=team, d=dream + 8 random chars), type (7 variants), status (pending/running/completed/failed/killed), description, timing fields, outputFile path, outputOffset for streaming reads.createTaskStateBase() on task launch. Status transitions: pending → running → completed/failed/killed. Stored in AppState.tasks.AppState — Global Application State (src/state/) #toolPermissionContext (permission mode, allow/deny/ask rules, bypass availability), fileHistoryState (undo/redo snapshots), tasks (running task map), fastMode, speculation state, and attribution tracking.setAppState(f: prev => next) pattern (functional update). React integration via useAppState(selector) hook.FileStateCache — LRU File Cache (src/utils/fileStateCache.ts) #QueryEngine instance. Shared between parent agent and forked sub-agents.| Hop | Bottleneck | Dominant cost |
|---|---|---|
| processUserInput | CPU: slash command parsing, attachment processing | ~1-5 ms |
| fetchSystemPromptParts | CPU: memory file loading, system prompt assembly | ~5-50 ms (CLAUDE.md discovery) |
| Claude API prefill | Network + GPU: prompt encoding | ~100 ms–10 s (proportional to context length) |
| Claude API decode | Network + GPU: token generation | ~50 ms–60 s (proportional to output length) |
| Permission pipeline (per tool call) | CPU + user wait: validateInput → hooks → rules → interactive prompt | ~0 ms (auto-allow) to unbounded (user prompt) |
| Tool execution (Bash) | CPU/disk: subprocess spawn + execution | ~50 ms–300 s (command dependent) |
| Tool execution (FileRead) | Disk I/O | ~1-10 ms |
| Tool execution (GrepTool) | CPU: ripgrep subprocess | ~10-500 ms (codebase size dependent) |
| Tool execution (WebFetch) | Network | ~100 ms–10 s |
| Session persistence | Disk: JSONL append (fire-and-forget) | ~1-5 ms (non-blocking) |
The API call dominates wall-clock time. The permission pipeline is the critical human-in-the-loop bottleneck — a single denied tool call with interactive prompt blocks the entire turn until the user responds. Auto-allow rules (alwaysAllow) eliminate this for trusted tool patterns.
The README describes the agent pattern as a simple while-true loop. The actual implementation in query.ts (785KB — the largest file in the codebase) is far more complex: it manages streaming state machines, concurrent tool dispatch, context compaction triggers, sub-agent lifecycle, transcript persistence, turn counting, budget enforcement, model fallback, snip boundaries, and structured output enforcement. The "simple loop" framing understates the complexity by roughly an order of magnitude.
無形式化作者証明 — 仅实证。
This is a decompiled commercial product, not a research artifact. No formal proofs exist for any component. Correctness assurances come from: (1) TypeScript's static type system with branded types (e.g., SystemPrompt via asSystemPrompt()) preventing certain classes of string/array confusion, (2) Zod schema validation on every tool input, (3) the permission pipeline enforcing security invariants via runtime checks, (4) session persistence providing crash recovery via JSONL replay, (5) the FileHistoryState snapshot system enabling undo/redo for destructive file operations, and (6) presumably extensive internal testing at Anthropic (not included in the decompiled source).
The key invariant — that the agent loop always terminates — is enforced by maxTurns (turn count limit) and maxBudgetUsd (cost limit), both optional. Without these guards, the loop runs until the model emits stop_reason: "end_turn" or the user aborts via AbortController.
| Mechanism | Where | Why |
|---|---|---|
| Single-threaded event loop | Node.js main process | All core logic runs on one thread; I/O is async |
| AsyncGenerator streaming | QueryEngine → query() → consumer | Full-chain streaming without callbacks; backpressure via generator protocol |
| AbortController | Every tool call, API request, sub-agent | Cooperative cancellation propagating through the entire call stack |
| Concurrent tool dispatch | StreamingToolExecutor | Tools marked isConcurrencySafe execute in parallel within a turn |
| Child processes | Sub-agents (fork mode), BashTool | Isolated execution contexts with IPC |
| AsyncLocalStorage | Per-agent context | Context isolation for sub-agents sharing the same Node.js process |
| Fire-and-forget writes | recordTranscript() | Non-blocking persistence with ordering guarantee via queue |
mutableMessages[] grows monotonically within a session. No garbage collection of old messages — this is what drives the need for context compression.autoCompact: summarizes old messages via a dedicated compact API call, replacing verbose history with a concise summarysnipCompact: removes zombie messages and stale markers (gated behind HISTORY_SNIP feature flag)contextCollapse: restructures context for efficiency (gated behind CONTEXT_COLLAPSE flag)validateInput() or checkPermissions() stalls the entire session. This is mitigated by convention (all tool methods are async) rather than enforcement.mutableMessages[] shared reference: Sub-agents forked in-process via AsyncLocalStorage share the parent's message array reference. The fork mode creates a fresh messages[] copy, but the in-process teammate mode shares state through setAppStateForTasks, creating a subtle mutation-ordering dependency.StreamingToolExecutor checks isConcurrencySafe() before parallel dispatch, but the check is per-tool, not per-input. Two concurrent FileEditTool calls to the same file could race despite both being individually "concurrency safe."recordTranscript() uses fire-and-forget writes with an ordering queue. If the process crashes between a message being yielded and the write completing, the session log loses that message. The REPL path awaits persistence for user messages (crash recovery) but fire-and-forgets assistant messages (performance).| Metric | Value |
|---|---|
| Bundle size | ~12 MB (single cli.js) |
| Cold start | ~1-3 s (Node.js startup + module init + settings load + MCP discovery) |
Warm start (--continue) | ~1-3 s + session replay time (proportional to session JSONL size) |
The dominant cost in every interaction is the Claude API call (network latency + model inference time). The local TypeScript runtime adds negligible overhead relative to API time. The performance-critical local paths are:
fetchSystemPromptParts() loads CLAUDE.md files, discovers skills, assembles system prompt. Cost scales with the number of memory files and their sizes.FileReadTool for large files, GrepTool for large codebases — both delegate to system utilities (Node.js fs and rg respectively), so performance matches those tools.--continue) replays the entire file.ToolSearchTool exists specifically to manage this — it defers loading of rarely-used tools.maxTurns per agent.| Step | Claim | Evidence | Depends on |
|---|---|---|---|
| 1 | A coding assistant must execute tools (file read/write, search, bash) to perform real work, not just generate text | Fundamental: text-only LLM responses cannot modify files, run tests, or inspect codebases | — |
| 2 | Unrestricted tool execution on a user's filesystem is a security risk requiring multi-layer permission gating | 4-stage permission pipeline: validateInput → hooks → rules → interactive prompt → checkPermissions, with separate allow/deny/ask rule sets per tool and glob pattern | Step 1 |
| 3 | Multi-turn coding conversations exceed context windows within minutes, requiring automatic compression | Three compression strategies (autoCompact, snipCompact, contextCollapse) triggered by token count thresholds; the largest single file in the codebase (query.ts, 785KB) exists partly because context management logic is interleaved with the agent loop | Step 1 |
| 4 | Complex tasks benefit from decomposition into sub-agents with isolated contexts but shared file state | 5 spawn modes (default, fork, worktree, remote, in-process teammate); fork mode copies messages but shares FileStateCache; worktree mode provides git-level isolation | Steps 1, 3 |
| 5 | Multiple consumer surfaces (interactive CLI, headless SDK, remote bridge) require a shared core engine with pluggable I/O | QueryEngine returns AsyncGenerator consumed by REPL (main.tsx), SDK (entrypoints/sdk/), and bridge (bridgeMain.ts) with surface-specific rendering | Steps 1-4 |
| 6 | The tool set must be dynamically extensible without modifying core loop logic | MCP protocol integration (mcp__ naming), plugin system (services/plugins/), skill system (skills/), and buildTool() factory all allow tool addition without touching query.ts | Steps 1, 2 |
| 7 | The 12-mechanism harness architecture is sufficient for production deployment | Shipped as Anthropic's primary coding CLI; 108 additional feature-gated modules indicate continued capability expansion within the same architecture | Steps 1-6 |
| Issue | Severity | Evidence |
|---|---|---|
query.ts at 785KB | Critical | Single file containing the entire agent loop + context management + streaming + tool dispatch interleaved. Refactoring risk is enormous — any change touches the critical path. |
| 108 dead-code-eliminated modules | High | Feature-gated modules reference types and interfaces that must be stubbed for the decompiled source to type-check. The scripts/stub-modules.mjs auto-generates stubs, but any stub-reality mismatch is silent. |
print.ts at 212KB, bridgeMain.ts at 115KB | High | Multiple 100KB+ files suggesting insufficient module decomposition in the rendering and bridge layers. |
bootstrap/state.ts at 56KB | Medium | Bootstrap state conflates session ID generation, persistence config, environment detection, and feature flag resolution into a single module. |
Bun compile-time intrinsics (feature(), MACRO) | Medium | Not reproducible with standard bundlers. The esbuild-based build in this repo transforms feature() → false, losing the ability to test any gated behavior. |
| No test suite in decompiled source | Medium | Zero test files shipped in the npm package. All testing presumably lives in Anthropic's internal monorepo. |
| React/Ink for terminal UI | Low-Medium | Full React component tree with hooks, context, and a design system for a CLI. The abstraction overhead is justified by the complexity of the permission dialogs, progress rendering, and multi-pane layout, but it means debugging the UI requires React mental model. |
feature() intrinsic → single 12MB cli.jscopy → transform → entry → bundle) in scripts/build.mjsprepare-src.mjs: source preparationtransform.mjs: feature() → false + MACRO.* replacementstub-modules.mjs: auto-generates stubs for 108 missing modules| Dependency | Role | Risk |
|---|---|---|
| React + Ink | Terminal UI rendering | Ink is niche (terminal React renderer); upstream maintenance varies |
| Zod | Schema validation for all tool inputs | Actively maintained, widely adopted |
| GrowthBook | Feature flags + A/B experiments | External service dependency for runtime behavior |
| ripgrep (external) | GrepTool execution | System dependency, not bundled |
| Node.js ≥ 18 | Runtime | Well-maintained |
| Metric | Value |
|---|---|
| Upstream stars | 11,910 (sanbuphy/learn-coding-agent) |
| Upstream forks | 19,728 |
| Fork stars (this repo) | 0 |
| License | None specified (Anthropic copyright disclaimer) |
| Maintainer | ZhaiFeiyue (fork); sanbuphy (upstream) |
| Nature | Decompiled proprietary source for research — not a community project |
| Upstream activity | Repository created 2026-03-31, single snapshot (v2.1.88), no subsequent updates |
| Contribution model | Not applicable — this is an extraction, not an open-source project accepting contributions |
| Bus factor | N/A (Anthropic's internal team maintains the actual product) |
| Governance | Anthropic (commercial entity) owns the product; this repo is an unauthorized decompilation |
This repository exists purely for research and educational analysis. It is not an active open-source project. The upstream sanbuphy/learn-coding-agent repo is a community research effort studying coding agent implementations, with significant community interest (11.9K stars, 19.7K forks) indicating broad demand for understanding agent internals.
| Dimension | Claude Code | Cursor (IDE) | GitHub Copilot CLI | Aider | Continue.dev |
|---|---|---|---|---|---|
| Architecture | TypeScript, React/Ink TUI | Electron + VS Code fork | Go CLI | Python CLI | TypeScript VS Code ext |
| Model | Claude (Anthropic) | Multi-model (Claude, GPT, etc.) | GPT (OpenAI) | Multi-model (GPT, Claude, etc.) | Multi-model |
| Tool execution | 40+ built-in tools + MCP + plugins | IDE-integrated tools | Shell commands | Shell + file edit | IDE-integrated |
| Permission system | 4-stage pipeline with rules + hooks | IDE-native permissions | Basic confirmation | Yes/no per edit | IDE-native |
| Multi-agent | 5 spawn modes, team protocols, coordinator | Sub-agents (Task tool) | None | None | None |
| Context management | 3 compression strategies (auto/snip/collapse) | IDE context engine | Conversation-based | Repo map + chat history | IDE context |
| MCP support | Full (stdio/sse/http/ws/sdk, OAuth) | MCP client | None | None | MCP client |
| Session persistence | JSONL with resume/fork/continue | IDE history | None | Git-based | IDE history |
| Sub-agent isolation | Fork (fresh messages), worktree (git isolation) | Git worktree | None | None | None |
| Extensibility | MCP + plugins + skills + hooks + slash commands | Extensions + rules | Limited | Limited | Extensions |
| Background tasks | DreamTask, daemon, cron | Background agents | None | None | None |
| UI framework | React/Ink (terminal) | Electron/VS Code | Minimal CLI | Minimal CLI | VS Code webview |
| Codebase size | ~512K LOC TypeScript | Proprietary | Proprietary | ~30K LOC Python | ~50K LOC TypeScript |
| License | Proprietary (Anthropic) | Proprietary | Proprietary | Apache-2.0 | Apache-2.0 |
| Open source | No (decompiled) | No | No | Yes | Yes |
Winner by scenario:
| Component | File | Role |
|---|---|---|
| Agent loop | src/query.ts (~785KB) | The while-true agent loop: API calls, tool dispatch, context management |
| Query lifecycle | src/QueryEngine.ts | submitMessage() → AsyncGenerator |
| Tool interface | src/Tool.ts | Tool definition + buildTool() factory |
| Tool registry | src/tools.ts | Tool list, presets, filtering |
| Task types | src/Task.ts | 7 task types, ID generation, status tracking |
| REPL bootstrap | src/main.tsx (4,683 LOC) | Interactive terminal entry, React/Ink rendering |
| CLI entry | src/entrypoints/cli.tsx | Version, help, daemon launch |
| SDK entry | src/entrypoints/sdk/ | Agent SDK types and sessions |
| Bridge lifecycle | src/bridge/bridgeMain.ts (115KB) | Claude Desktop / remote session management |
| Bridge REPL | src/bridge/replBridge.ts (100KB) | REPL bridge controller |
| Output rendering | src/cli/print.ts (212KB) | Terminal output formatting |
| Slash commands | src/commands.ts + src/commands/ | 80+ commands with feature-gated imports |
| API client | src/services/api/claude.ts | Streaming Claude API calls with retry |
| Context compression | src/services/compact/ | autoCompact + snipCompact + contextCollapse |
| Tool executor | src/services/tools/ | StreamingToolExecutor + toolOrchestration |
| MCP connection | src/services/mcp/ | MCPConnectionManager (discovery, auth, lifecycle) |
| Permission engine | src/utils/permissions/ | Rule evaluation: allow/deny/ask per tool + pattern |
| Memory system | src/memdir/memdir.ts | CLAUDE.md discovery and loading |
| Skill loader | src/skills/loadSkillsDir.ts | Skill directory discovery |
| App state | src/state/AppStateStore.ts | State definition + React provider |
| Bootstrap | src/bootstrap/state.ts (56KB) | Session ID, persistence, environment |
| File history | src/utils/fileHistory.ts | Undo/redo snapshots |
| File cache | src/utils/fileStateCache.ts | LRU file content cache |
| Session storage | src/utils/sessionStorage.ts | JSONL session persistence |
| Build script | scripts/build.mjs | 4-phase esbuild bundler |
| Stub generator | scripts/stub-modules.mjs | Auto-stub for 108 missing feature-gated modules |
AsyncGenerator as the universal streaming primitive: QueryEngine.submitMessage() returns AsyncGenerator, which the REPL, SDK, and bridge all consume through for await...of. This means the entire chain — from API SSE stream through tool execution to UI rendering — uses a single pull-based streaming mechanism. Backpressure is natural: if the consumer is slow (e.g., rendering a large tool output), the generator suspends, which suspends the tool executor, which suspends the API stream reader. No explicit flow control logic is needed anywhere in the pipeline. This is the architectural decision that makes the 40+ tools, 12 harness mechanisms, and 3 consumer surfaces composable without a message bus or event emitter.buildTool() factory providing safe defaults: Rather than requiring each of 40+ tools to implement the full ~30-method Tool interface, buildTool(def) fills in sensible defaults: maxResultSizeChars = 30000, isReadOnly = () => false, isConcurrencySafe = () => false, renderToolUseMessage using generic formatting, etc. Tool authors only specify the 4-5 methods that differ from defaults. This reduces the per-tool boilerplate from ~200 lines to ~30 lines, which is what makes 40+ tools maintainable. The factory also enforces naming conventions and registers tools with the search index.string — it is a branded type SystemPrompt created only via asSystemPrompt(). This prevents a common bug where arbitrary strings are passed as system prompts (which would bypass prompt injection protections). The TypeScript compiler enforces this at build time — no runtime cost.recordTranscript() is non-blocking (fire-and-forget) to avoid adding disk I/O latency to every turn. But it maintains an internal write queue that guarantees ordering — message N is always written before message N+1. User messages use a blocking variant (crash recovery: if the process dies mid-turn, the user's prompt is already persisted and can be replayed on resume). Assistant messages use fire-and-forget (performance: don't block the next turn on disk write).AsyncGenerator design provides backpressure, composability across surfaces, and natural cancellation without explicit flow control. This pattern is directly applicable to any agent framework.messages[] prevents context contamination between parent and child agents, while shared FileStateCache ensures file reads are consistent without redundant I/O. The worktree mode adds git-level isolation for truly independent parallel work.The decompiled source reveals that the shipped product (v2.1.88) exposes roughly 40% of the implemented capability surface. The 108 feature-gated modules include:
These modules indicate the direction of agent evolution: from reactive (user-initiated) to proactive (agent-initiated), from single-session to persistent-daemon, from text to multimodal (voice, browser). The architecture's 12-mechanism harness was designed to accommodate this evolution — the same QueryEngine core supports all these modes through the same AsyncGenerator streaming interface.