diff --git a/README.md b/README.md index a1c2ddf..de25b27 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,24 @@ -# Claude Code v2.1.88 Source Code +# Claude Code v2.1.88 — Source Code Analysis -From npm package `@anthropic-ai/claude-code` version **2.1.88**. +> Extracted from npm package `@anthropic-ai/claude-code` version **2.1.88**. +> The published package ships a single bundled `cli.js` (~12MB). The `src/` directory in this repo contains the **unbundled TypeScript source** extracted from the npm tarball. -The published package ships a single bundled `cli.js` (~12MB). The `src/` directory in this repo contains the **decompiled/unbundled TypeScript source** extracted from the npm tarball. +--- + +## Copyright & Disclaimer + +``` +Copyright (c) Anthropic PBC. All rights reserved. + +All source code in this repository is the intellectual property of Anthropic. +This repository is provided strictly for technical research and educational purposes. +Commercial use is strictly prohibited. + +If you are the copyright owner and believe this repository infringes your rights, +please contact the repository owner for immediate removal. +``` + +--- ## Stats @@ -10,59 +26,727 @@ The published package ships a single bundled `cli.js` (~12MB). The `src/` direct |------|-------| | Source files (.ts/.tsx) | ~1,884 | | Lines of code | ~512,664 | +| Largest single file | `query.ts` (~785KB) | +| Built-in tools | ~40+ | +| Slash commands | ~80+ | | Dependencies (node_modules) | ~192 packages | +| Runtime | Bun (compiled to Node.js >= 18 bundle) | -## Directory Structure +--- + +## The Agent Pattern + +``` + THE CORE LOOP + ============= + + User --> messages[] --> Claude API --> response + | + stop_reason == "tool_use"? + / \ + yes no + | | + execute tools return text + append tool_result + loop back -----------------> messages[] + + + That is the minimal agent loop. Claude Code wraps this loop + with a production-grade harness: permissions, streaming, + concurrency, compaction, sub-agents, persistence, and MCP. +``` + +--- + +## Architecture Overview + +``` +┌─────────────────────────────────────────────────────────────────────┐ +│ ENTRY LAYER │ +│ cli.tsx ──> main.tsx ──> REPL.tsx (interactive) │ +│ └──> QueryEngine.ts (headless/SDK) │ +└──────────────────────────────┬──────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────────────┐ +│ QUERY ENGINE │ +│ submitMessage(prompt) ──> AsyncGenerator │ +│ │ │ +│ ├── fetchSystemPromptParts() ──> assemble system prompt │ +│ ├── processUserInput() ──> handle /commands │ +│ ├── query() ──> main agent loop │ +│ │ ├── StreamingToolExecutor ──> parallel tool execution │ +│ │ ├── autoCompact() ──> context compression │ +│ │ └── runTools() ──> tool orchestration │ +│ └── yield SDKMessage ──> stream to consumer │ +└──────────────────────────────┬──────────────────────────────────────┘ + │ + ┌────────────────┼────────────────┐ + ▼ ▼ ▼ +┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐ +│ TOOL SYSTEM │ │ SERVICE LAYER │ │ STATE LAYER │ +│ │ │ │ │ │ +│ Tool Interface │ │ api/claude.ts │ │ AppState Store │ +│ ├─ call() │ │ API client │ │ ├─ permissions │ +│ ├─ validate() │ │ compact/ │ │ ├─ fileHistory │ +│ ├─ checkPerms() │ │ auto-compact │ │ ├─ agents │ +│ ├─ render() │ │ mcp/ │ │ └─ fastMode │ +│ └─ prompt() │ │ MCP protocol │ │ │ +│ │ │ analytics/ │ │ React Context │ +│ 40+ Built-in: │ │ telemetry │ │ ├─ useAppState │ +│ ├─ BashTool │ │ tools/ │ │ └─ useSetState │ +│ ├─ FileRead │ │ executor │ │ │ +│ ├─ FileEdit │ │ plugins/ │ └──────────────────┘ +│ ├─ Glob/Grep │ │ loader │ +│ ├─ AgentTool │ │ settingsSync/ │ +│ ├─ WebFetch │ │ cross-device │ +│ └─ MCPTool │ │ oauth/ │ +│ │ │ auth flow │ +└──────────────────┘ └─────────────────┘ + │ │ + ▼ ▼ +┌──────────────────┐ ┌─────────────────┐ +│ TASK SYSTEM │ │ BRIDGE LAYER │ +│ │ │ │ +│ Task Types: │ │ bridgeMain.ts │ +│ ├─ local_bash │ │ session mgmt │ +│ ├─ local_agent │ │ bridgeApi.ts │ +│ ├─ remote_agent │ │ HTTP client │ +│ ├─ in_process │ │ workSecret.ts │ +│ ├─ dream │ │ auth tokens │ +│ └─ workflow │ │ sessionRunner │ +│ │ │ process spawn │ +│ ID: prefix+8chr │ └─────────────────┘ +│ b=bash a=agent │ +│ r=remote t=team │ +└──────────────────┘ +``` + +--- + +## Data Flow: A Single Query Lifecycle + +``` + USER INPUT (prompt / slash command) + │ + ▼ + processUserInput() ← parse /commands, build UserMessage + │ + ▼ + fetchSystemPromptParts() ← tools → prompt sections, CLAUDE.md memory + │ + ▼ + recordTranscript() ← persist user message to disk (JSONL) + │ + ▼ + ┌─→ normalizeMessagesForAPI() ← strip UI-only fields, compact if needed + │ │ + │ ▼ + │ Claude API (streaming) ← POST /v1/messages with tools + system prompt + │ │ + │ ▼ + │ stream events ← message_start → content_block_delta → message_stop + │ │ + │ ├─ text block ──────────────→ yield to consumer (SDK / REPL) + │ │ + │ └─ tool_use block? + │ │ + │ ▼ + │ StreamingToolExecutor ← partition: concurrent-safe vs serial + │ │ + │ ▼ + │ canUseTool() ← permission check (hooks + rules + UI prompt) + │ │ + │ ├─ DENY ────────────────→ append tool_result(error), continue loop + │ │ + │ └─ ALLOW + │ │ + │ ▼ + │ tool.call() ← execute the tool (Bash, Read, Edit, etc.) + │ │ + │ ▼ + │ append tool_result ← push to messages[], recordTranscript() + │ │ + └─────────┘ ← loop back to API call + │ + ▼ (stop_reason != "tool_use") + yield result message ← final text, usage, cost, session_id +``` + +--- + +## Tool System Architecture + +``` + TOOL INTERFACE + ============== + + buildTool(definition) ──> Tool + + Every tool implements: + ┌────────────────────────────────────────────────────────┐ + │ LIFECYCLE │ + │ ├── validateInput() → reject bad args early │ + │ ├── checkPermissions() → tool-specific authz │ + │ └── call() → execute and return result │ + │ │ + │ CAPABILITIES │ + │ ├── isEnabled() → feature gate check │ + │ ├── isConcurrencySafe() → can run in parallel? │ + │ ├── isReadOnly() → no side effects? │ + │ ├── isDestructive() → irreversible ops? │ + │ └── interruptBehavior() → cancel or block on user? │ + │ │ + │ RENDERING (React/Ink) │ + │ ├── renderToolUseMessage() → input display │ + │ ├── renderToolResultMessage() → output display │ + │ ├── renderToolUseProgressMessage() → spinner/status │ + │ └── renderGroupedToolUse() → parallel tool groups │ + │ │ + │ AI FACING │ + │ ├── prompt() → tool description for LLM │ + │ ├── description() → dynamic description │ + │ └── mapToolResultToAPI() → format for API response │ + └────────────────────────────────────────────────────────┘ +``` + +### Complete Tool Inventory + +``` + FILE OPERATIONS SEARCH & DISCOVERY EXECUTION + ═════════════════ ══════════════════════ ══════════ + FileReadTool GlobTool BashTool + FileEditTool GrepTool PowerShellTool + FileWriteTool ToolSearchTool + NotebookEditTool INTERACTION + ═══════════ + WEB & NETWORK AGENT / TASK AskUserQuestionTool + ════════════════ ══════════════════ BriefTool + WebFetchTool AgentTool + WebSearchTool SendMessageTool PLANNING & WORKFLOW + TeamCreateTool ════════════════════ + MCP PROTOCOL TeamDeleteTool EnterPlanModeTool + ══════════════ TaskCreateTool ExitPlanModeTool + MCPTool TaskGetTool EnterWorktreeTool + ListMcpResourcesTool TaskUpdateTool ExitWorktreeTool + ReadMcpResourceTool TaskListTool TodoWriteTool + TaskStopTool + TaskOutputTool SYSTEM + ════════ + SKILLS & EXTENSIONS ConfigTool + ═════════════════════ SkillTool + SkillTool ScheduleCronTool + LSPTool SleepTool + TungstenTool +``` + +--- + +## Permission System + +``` + TOOL CALL REQUEST + │ + ▼ + ┌─ validateInput() ──────────────────────────────────┐ + │ reject invalid inputs before any permission check │ + └────────────────────┬───────────────────────────────┘ + │ + ▼ + ┌─ PreToolUse Hooks ─────────────────────────────────┐ + │ user-defined shell commands (settings.json hooks) │ + │ can: approve, deny, or modify input │ + └────────────────────┬───────────────────────────────┘ + │ + ▼ + ┌─ Permission Rules ─────────────────────────────────┐ + │ alwaysAllowRules: match tool name/pattern → auto │ + │ alwaysDenyRules: match tool name/pattern → deny │ + │ alwaysAskRules: match tool name/pattern → ask │ + │ Sources: settings, CLI args, session decisions │ + └────────────────────┬───────────────────────────────┘ + │ + no rule match? + │ + ▼ + ┌─ Interactive Prompt ───────────────────────────────┐ + │ User sees tool name + input │ + │ Options: Allow Once / Allow Always / Deny │ + └────────────────────┬───────────────────────────────┘ + │ + ▼ + ┌─ checkPermissions() ───────────────────────────────┐ + │ Tool-specific logic (e.g. path sandboxing) │ + └────────────────────┬───────────────────────────────┘ + │ + APPROVED → tool.call() +``` + +--- + +## Sub-Agent & Multi-Agent Architecture + +``` + MAIN AGENT + ========== + │ + ┌───────────────┼───────────────┐ + ▼ ▼ ▼ + ┌──────────────┐ ┌──────────┐ ┌──────────────┐ + │ FORK AGENT │ │ REMOTE │ │ IN-PROCESS │ + │ │ │ AGENT │ │ TEAMMATE │ + │ Fork process │ │ Bridge │ │ Same process │ + │ Shared cache │ │ session │ │ Async context│ + │ Fresh msgs[] │ │ Isolated │ │ Shared state │ + └──────────────┘ └──────────┘ └──────────────┘ + + SPAWN MODES: + ├─ default → in-process, shared conversation + ├─ fork → child process, fresh messages[], shared file cache + ├─ worktree → isolated git worktree + fork + └─ remote → bridge to Claude Code Remote / container + + COMMUNICATION: + ├─ SendMessageTool → agent-to-agent messages + ├─ TaskCreate/Update → shared task board + └─ TeamCreate/Delete → team lifecycle management + + SWARM MODE (feature-gated): + ┌─────────────────────────────────────────────┐ + │ Lead Agent │ + │ ├── Teammate A ──> claims Task 1 │ + │ ├── Teammate B ──> claims Task 2 │ + │ └── Teammate C ──> claims Task 3 │ + │ │ + │ Shared: task board, message inbox │ + │ Isolated: messages[], file cache, cwd │ + └─────────────────────────────────────────────┘ +``` + +--- + +## Context Management (Compact System) + +``` + CONTEXT WINDOW BUDGET + ═════════════════════ + + ┌─────────────────────────────────────────────────────┐ + │ System Prompt (tools, permissions, CLAUDE.md) │ + │ ══════════════════════════════════════════════ │ + │ │ + │ Conversation History │ + │ ┌─────────────────────────────────────────────┐ │ + │ │ [compacted summary of older messages] │ │ + │ │ ═══════════════════════════════════════════ │ │ + │ │ [compact_boundary marker] │ │ + │ │ ─────────────────────────────────────────── │ │ + │ │ [recent messages — full fidelity] │ │ + │ │ user → assistant → tool_use → tool_result │ │ + │ └─────────────────────────────────────────────┘ │ + │ │ + │ Current Turn (user + assistant response) │ + └─────────────────────────────────────────────────────┘ + + THREE COMPRESSION STRATEGIES: + ├─ autoCompact → triggers when token count exceeds threshold + │ summarizes old messages via a compact API call + ├─ snipCompact → removes zombie messages and stale markers + │ (HISTORY_SNIP feature flag) + └─ contextCollapse → restructures context for efficiency + (CONTEXT_COLLAPSE feature flag) + + COMPACTION FLOW: + messages[] ──> getMessagesAfterCompactBoundary() + │ + ▼ + older messages ──> Claude API (summarize) ──> compact summary + │ + ▼ + [summary] + [compact_boundary] + [recent messages] +``` + +--- + +## MCP (Model Context Protocol) Integration + +``` + ┌─────────────────────────────────────────────────────────┐ + │ MCP ARCHITECTURE │ + │ │ + │ MCPConnectionManager.tsx │ + │ ├── Server Discovery (config from settings.json) │ + │ │ ├── stdio → spawn child process │ + │ │ ├── sse → HTTP EventSource │ + │ │ ├── http → Streamable HTTP │ + │ │ ├── ws → WebSocket │ + │ │ └── sdk → in-process transport │ + │ │ │ + │ ├── Client Lifecycle │ + │ │ ├── connect → initialize → list tools │ + │ │ ├── tool calls via MCPTool wrapper │ + │ │ └── disconnect / reconnect with backoff │ + │ │ │ + │ ├── Authentication │ + │ │ ├── OAuth 2.0 flow (McpOAuthConfig) │ + │ │ ├── Cross-App Access (XAA / SEP-990) │ + │ │ └── API key via headers │ + │ │ │ + │ └── Tool Registration │ + │ ├── mcp____ naming convention │ + │ ├── Dynamic schema from MCP server │ + │ ├── Permission passthrough to Claude Code │ + │ └── Resource listing (ListMcpResourcesTool) │ + │ │ + └─────────────────────────────────────────────────────────┘ +``` + +--- + +## Bridge Layer (Claude Desktop / Remote) + +``` + Claude Desktop / Web / Cowork Claude Code CLI + ══════════════════════════ ═════════════════ + + ┌───────────────────┐ ┌──────────────────┐ + │ Bridge Client │ ←─ HTTP ──→ │ bridgeMain.ts │ + │ (Desktop App) │ │ │ + └───────────────────┘ │ Session Manager │ + │ ├── spawn CLI │ + PROTOCOL: │ ├── poll status │ + ├─ JWT authentication │ ├── relay msgs │ + ├─ Work secret exchange │ └── capacityWake │ + ├─ Session lifecycle │ │ + │ ├── create │ Backoff: │ + │ ├── run │ ├─ conn: 2s→2m │ + │ └─ stop │ └─ gen: 500ms→30s│ + └─ Token refresh scheduler └──────────────────┘ +``` + +--- + +## Session Persistence + +``` + SESSION STORAGE + ══════════════ + + ~/.claude/projects//sessions/ + └── .jsonl ← append-only log + ├── {"type":"user",...} + ├── {"type":"assistant",...} + ├── {"type":"progress",...} + └── {"type":"system","subtype":"compact_boundary",...} + + RESUME FLOW: + getLastSessionLog() ──> parse JSONL ──> rebuild messages[] + │ + ├── --continue → last session in cwd + ├── --resume → specific session + └── --fork-session → new ID, copy history + + PERSISTENCE STRATEGY: + ├─ User messages → await write (blocking, for crash recovery) + ├─ Assistant msgs → fire-and-forget (order-preserving queue) + ├─ Progress → inline write (dedup on next query) + └─ Flush → on result yield / cowork eager flush +``` + +--- + +## Feature Flag System + +``` + DEAD CODE ELIMINATION (Bun compile-time) + ══════════════════════════════════════════ + + feature('FLAG_NAME') ──→ true → included in bundle + ──→ false → stripped from bundle + + FLAGS (observed in source): + ├─ COORDINATOR_MODE → multi-agent coordinator + ├─ HISTORY_SNIP → aggressive history trimming + ├─ CONTEXT_COLLAPSE → context restructuring + ├─ DAEMON → background daemon workers + ├─ AGENT_TRIGGERS → cron/remote triggers + ├─ AGENT_TRIGGERS_REMOTE → remote trigger support + ├─ MONITOR_TOOL → MCP monitoring tool + ├─ WEB_BROWSER_TOOL → browser automation + ├─ VOICE_MODE → voice input/output + ├─ TEMPLATES → job classifier + ├─ EXPERIMENTAL_SKILL_SEARCH → skill discovery + ├─ KAIROS → push notifications, file sends + ├─ PROACTIVE → sleep tool, proactive behavior + ├─ OVERFLOW_TEST_TOOL → testing tool + ├─ TERMINAL_PANEL → terminal capture + ├─ WORKFLOW_SCRIPTS → workflow tool + ├─ CHICAGO_MCP → computer use MCP + ├─ DUMP_SYSTEM_PROMPT → prompt extraction (ant-only) + ├─ UDS_INBOX → peer discovery + ├─ ABLATION_BASELINE → experiment ablation + └─ UPGRADE_NOTICE → upgrade notifications + + RUNTIME GATES: + ├─ process.env.USER_TYPE === 'ant' → Anthropic-internal features + └─ GrowthBook feature flags → A/B experiments at runtime +``` + +--- + +## State Management + +``` + ┌──────────────────────────────────────────────────────────┐ + │ AppState Store │ + │ │ + │ AppState { │ + │ toolPermissionContext: { │ + │ mode: PermissionMode, ← default/plan/etc │ + │ additionalWorkingDirectories, │ + │ alwaysAllowRules, ← auto-approve │ + │ alwaysDenyRules, ← auto-reject │ + │ alwaysAskRules, ← always prompt │ + │ isBypassPermissionsModeAvailable │ + │ }, │ + │ fileHistory: FileHistoryState, ← undo snapshots │ + │ attribution: AttributionState, ← commit tracking │ + │ verbose: boolean, │ + │ mainLoopModel: string, ← active model │ + │ fastMode: FastModeState, │ + │ speculation: SpeculationState │ + │ } │ + │ │ + │ React Integration: │ + │ ├── AppStateProvider → creates store via createContext │ + │ ├── useAppState(sel) → selector-based subscriptions │ + │ └── useSetAppState() → immer-style updater function │ + └──────────────────────────────────────────────────────────┘ +``` + +--- + +## The 12 Progressive Harness Mechanisms + +This source code demonstrates 12 layered mechanisms that a production AI agent harness needs beyond the basic loop. Each builds on the previous: + +``` + s01 THE LOOP "One loop & Bash is all you need" + query.ts: the while-true loop that calls Claude API, + checks stop_reason, executes tools, appends results. + + s02 TOOL DISPATCH "Adding a tool = adding one handler" + Tool.ts + tools.ts: every tool registers into the dispatch + map. The loop stays identical. buildTool() factory provides + safe defaults. + + s03 PLANNING "An agent without a plan drifts" + EnterPlanModeTool/ExitPlanModeTool + TodoWriteTool: + list steps first, then execute. Doubles completion rate. + + s04 SUB-AGENTS "Break big tasks; clean context per subtask" + AgentTool + forkSubagent.ts: each child gets fresh messages[], + keeping the main conversation clean. + + s05 KNOWLEDGE ON DEMAND "Load knowledge when you need it" + SkillTool + memdir/: inject via tool_result, not system prompt. + CLAUDE.md files loaded lazily per directory. + + s06 CONTEXT COMPRESSION "Context fills up; make room" + services/compact/: three-layer strategy: + autoCompact (summarize) + snipCompact (trim) + contextCollapse + + s07 PERSISTENT TASKS "Big goals → small tasks → disk" + TaskCreate/Update/Get/List: file-based task graph with + status tracking, dependencies, and persistence. + + s08 BACKGROUND TASKS "Slow ops in background; agent keeps thinking" + DreamTask + LocalShellTask: daemon threads run commands, + inject notifications on completion. + + s09 AGENT TEAMS "Too big for one → delegate to teammates" + TeamCreate/Delete + InProcessTeammateTask: persistent + teammates with async mailboxes. + + s10 TEAM PROTOCOLS "Shared communication rules" + SendMessageTool: one request-response pattern drives + all negotiation between agents. + + s11 AUTONOMOUS AGENTS "Teammates scan and claim tasks themselves" + coordinator/coordinatorMode.ts: idle cycle + auto-claim, + no need for lead to assign each task. + + s12 WORKTREE ISOLATION "Each works in its own directory" + EnterWorktreeTool/ExitWorktreeTool: tasks manage goals, + worktrees manage directories, bound by ID. +``` + +--- + +## Key Design Patterns + +| Pattern | Where | Purpose | +|---------|-------|---------| +| **AsyncGenerator streaming** | `QueryEngine`, `query()` | Full-chain streaming from API to consumer | +| **Builder + Factory** | `buildTool()` | Safe defaults for tool definitions | +| **Branded Types** | `SystemPrompt`, `asSystemPrompt()` | Prevent string/array confusion | +| **Feature Flags + DCE** | `feature()` from `bun:bundle` | Compile-time dead code elimination | +| **Discriminated Unions** | `Message` types | Type-safe message handling | +| **Observer + State Machine** | `StreamingToolExecutor` | Tool execution lifecycle tracking | +| **Snapshot State** | `FileHistoryState` | Undo/redo for file operations | +| **Ring Buffer** | Error log | Bounded memory for long sessions | +| **Fire-and-Forget Write** | `recordTranscript()` | Non-blocking persistence with ordering | +| **Lazy Schema** | `lazySchema()` | Defer Zod schema evaluation for performance | +| **Context Isolation** | `AsyncLocalStorage` | Per-agent context in shared process | + +--- + +## Directory Reference ``` src/ -├── main.tsx # Main entry (~4,683 lines) -├── QueryEngine.ts # Core query lifecycle engine -├── query.ts # Query main loop (~785KB, largest file) +├── main.tsx # REPL bootstrap, 4,683 lines +├── QueryEngine.ts # SDK/headless query lifecycle engine +├── query.ts # Main agent loop (785KB, largest file) ├── Tool.ts # Tool interface + buildTool factory -├── Task.ts # Task types and lifecycle -├── tools.ts # Tool registry and presets -├── bridge/ # Bridge to Claude Desktop / remote -├── cli/ # CLI handlers and transports -├── commands/ # Slash commands (~80+) +├── Task.ts # Task types, IDs, state base +├── tools.ts # Tool registry, presets, filtering +├── commands.ts # Slash command definitions +├── context.ts # User input context +├── cost-tracker.ts # API cost accumulation +├── setup.ts # First-run setup flow +│ +├── bridge/ # Claude Desktop / remote bridge +│ ├── bridgeMain.ts # Session lifecycle manager +│ ├── bridgeApi.ts # HTTP client +│ ├── bridgeConfig.ts # Connection config +│ ├── bridgeMessaging.ts # Message relay +│ ├── sessionRunner.ts # Process spawning +│ ├── jwtUtils.ts # JWT refresh +│ ├── workSecret.ts # Auth tokens +│ └── capacityWake.ts # Capacity-based wakeup +│ +├── cli/ # CLI infrastructure +│ ├── handlers/ # Command handlers +│ └── transports/ # I/O transports (stdio, structured) +│ +├── commands/ # ~80 slash commands +│ ├── agents/ # Agent management +│ ├── compact/ # Context compaction +│ ├── config/ # Settings management +│ ├── help/ # Help display +│ ├── login/ # Authentication +│ ├── mcp/ # MCP server management +│ ├── memory/ # Memory system +│ ├── plan/ # Plan mode +│ ├── resume/ # Session resume +│ ├── review/ # Code review +│ └── ... # 70+ more commands +│ ├── components/ # React/Ink terminal UI -├── entrypoints/ # CLI, SDK, MCP entry points +│ ├── design-system/ # Reusable UI primitives +│ ├── messages/ # Message rendering +│ ├── permissions/ # Permission dialogs +│ ├── PromptInput/ # Input field + suggestions +│ ├── LogoV2/ # Branding + welcome screen +│ ├── Settings/ # Settings panels +│ ├── Spinner.tsx # Loading indicators +│ └── ... # 40+ component groups +│ +├── entrypoints/ # Application entry points +│ ├── cli.tsx # CLI main (version, help, daemon) +│ ├── sdk/ # Agent SDK (types, sessions) +│ └── mcp.ts # MCP server entry +│ ├── hooks/ # React hooks -├── screens/ # REPL and other screens -├── services/ # API, analytics, MCP, compact, plugins -├── state/ # AppState management -├── tasks/ # Task implementations (bash, agent, remote) -├── tools/ # Tool implementations (~40+) -│ ├── AgentTool/ # Sub-agent spawning -│ ├── BashTool/ # Shell execution -│ ├── FileEditTool/ # File editing -│ ├── FileReadTool/ # File reading -│ ├── FileWriteTool/ # File writing -│ ├── GlobTool/ # File glob search -│ ├── GrepTool/ # Content grep search -│ ├── MCPTool/ # MCP protocol tools -│ ├── WebFetchTool/ # Web fetching -│ └── ... # 30+ more tools -├── types/ # TypeScript type definitions -├── utils/ # Utilities +│ ├── useCanUseTool.tsx # Permission checking +│ ├── useReplBridge.tsx # Bridge connection +│ ├── notifs/ # Notification hooks +│ └── toolPermission/ # Tool permission handlers +│ +├── services/ # Business logic layer +│ ├── api/ # Claude API client +│ │ ├── claude.ts # Streaming API calls +│ │ ├── errors.ts # Error categorization +│ │ └── withRetry.ts # Retry logic +│ ├── analytics/ # Telemetry + GrowthBook +│ ├── compact/ # Context compression +│ ├── mcp/ # MCP connection management +│ ├── tools/ # Tool execution engine +│ │ ├── StreamingToolExecutor.ts # Parallel tool runner +│ │ └── toolOrchestration.ts # Batch orchestration +│ ├── plugins/ # Plugin loader +│ └── settingsSync/ # Cross-device settings +│ +├── state/ # Application state +│ ├── AppStateStore.ts # Store definition +│ └── AppState.tsx # React provider + hooks +│ +├── tasks/ # Task implementations +│ ├── LocalShellTask/ # Bash command execution +│ ├── LocalAgentTask/ # Sub-agent execution +│ ├── RemoteAgentTask/ # Remote agent via bridge +│ ├── InProcessTeammateTask/ # In-process teammate +│ └── DreamTask/ # Background thinking +│ +├── tools/ # 40+ tool implementations +│ ├── AgentTool/ # Sub-agent spawning + fork +│ ├── BashTool/ # Shell command execution +│ ├── FileReadTool/ # File reading (PDF, image, etc) +│ ├── FileEditTool/ # String-replace editing +│ ├── FileWriteTool/ # Full file creation +│ ├── GlobTool/ # File pattern search +│ ├── GrepTool/ # Content search (ripgrep) +│ ├── WebFetchTool/ # HTTP fetching +│ ├── WebSearchTool/ # Web search +│ ├── MCPTool/ # MCP tool wrapper +│ ├── SkillTool/ # Skill invocation +│ ├── AskUserQuestionTool/ # User interaction +│ └── ... # 30+ more tools +│ +├── types/ # Type definitions +│ ├── message.ts # Message discriminated unions +│ ├── permissions.ts # Permission types +│ ├── tools.ts # Tool progress types +│ └── ids.ts # Branded ID types +│ +├── utils/ # Utilities (largest directory) +│ ├── permissions/ # Permission rule engine +│ ├── messages/ # Message formatting +│ ├── model/ # Model selection logic +│ ├── settings/ # Settings management +│ ├── sandbox/ # Sandbox runtime adapter +│ ├── hooks/ # Hook execution +│ ├── memory/ # Memory system utils +│ ├── git/ # Git operations +│ ├── github/ # GitHub API +│ ├── bash/ # Bash execution helpers +│ ├── swarm/ # Multi-agent swarm +│ ├── telemetry/ # Telemetry reporting +│ └── ... # 30+ more util groups +│ └── vendor/ # Native module source stubs + ├── audio-capture-src/ # Audio input + ├── image-processor-src/ # Image processing + ├── modifiers-napi-src/ # Native modifiers + └── url-handler-src/ # URL handling ``` -## Key Architecture +--- -- **Runtime**: Bun (uses `bun:bundle` feature flags, macros) -- **UI**: React + Ink (terminal rendering) -- **API**: Anthropic Claude API with streaming -- **Protocol**: MCP (Model Context Protocol) for tool extensions -- **Build**: Bun bundler produces single `cli.js` with dead code elimination +## Build Notes -## Notes +This source is **not directly compilable** from this repo alone: -- This source is **not directly compilable** — it lacks `tsconfig.json`, build scripts, and the full Bun build pipeline -- Feature flags (`feature('...')`) are compile-time gated via Bun's dead code elimination -- `process.env.USER_TYPE === 'ant'` sections are Anthropic-internal only -- The compiled `cli.js` is a self-contained bundle requiring only Node.js >= 18 +- Missing `tsconfig.json`, build scripts, and Bun bundler config +- `feature()` calls are Bun compile-time intrinsics — resolved during bundling +- `MACRO.VERSION` is injected at build time +- `process.env.USER_TYPE === 'ant'` sections are Anthropic-internal +- The compiled `cli.js` is a self-contained 12MB bundle requiring only Node.js >= 18 +- Source maps (`cli.js.map`, 60MB) map back to these source files for debugging + +--- ## License -See the original package for license information. +All source code in this repository is copyright **Anthropic PBC**. This repository is for technical research and education only. See the original npm package for full license terms.