How leeyeel/claude-code works
1. Overall shape
- This is a TypeScript/Bun monorepo for a terminal-based agentic developer tool.
- The core architecture is a loop between the CLI/UI, the LLM query engine, tool execution, and state/history management.
2. Primary runtime boundary
- src/main.tsx and src/entrypoints/cli.tsx bootstrap the app.
- The user-facing runtime is an Ink/React terminal UI, not a browser app.
- Commands and feature-gated subsystems are loaded conditionally at startup to keep boot fast.
3. Core orchestration layer
- src/QueryEngine.ts, src/Tool.ts, and src/Task.ts define the central agent runtime contracts.
- The query engine drives model calls, streaming responses, tool-call loops, retries, token accounting, and turn completion.
- Tool abstractions define schemas, permission hooks, and execution progress so every capability flows through one shared runtime.
4. Tool execution subsystem
- src/tools/ contains the major capability boundary of the system.
- Tools cover local environment access (BashTool, file read/write/edit, search), model-adjacent behavior (AgentTool, SkillTool, MCPTool, LSPTool), workflow operations (Task*, plan/worktree toggles), and external interaction (WebFetchTool, WebSearchTool, remote triggers).
- Most user-visible capabilities are exposed to the model through this tool layer rather than directly through UI code.
5. Slash command subsystem
- src/commands/ implements the CLI command surface, with src/commands.ts acting as the registry.
- These commands are the user’s control plane for session management, configuration, review, diffing, memory, tasks, plugins, bridge/remote features, and environment diagnostics.
- Commands largely orchestrate subsystems rather than containing domain logic themselves.
6. Terminal UI and interaction model
- src/components/ and src/screens/ hold the Ink UI, dialogs, and full-screen flows.
- The UI renders conversation messages, tool activity, permission prompts, onboarding, settings, and task/status views.
- src/hooks/ and src/context/ connect user input, notifications, overlays, keybindings, and app state into the reactive UI.
7. State, history, and session lifecycle
- src/state/, src/history.ts, and src/assistant/sessionHistory.ts manage conversation state and session persistence.
- src/bootstrap/, src/setup.ts, and src/utils/session* modules handle startup state, restore/resume flows, and session metadata.
- The app treats sessions as durable units that can be resumed, compacted, exported, or shared.
8. Permissions and safety boundary
- src/hooks/toolPermission/, src/components/permissions/, and src/utils/permissions/ form the approval system around risky actions.
- This boundary mediates shell execution, file writes, notebook edits, web access, MCP actions, and other privileged operations.
- Permission mode, policy rules, sandboxing, and denial tracking are central to the architecture rather than bolted on.
9. External integrations
- src/services/api/ is the main Anthropic API/client boundary.
- src/services/oauth/, src/services/analytics/, src/services/mcp/, src/services/lsp/, and src/services/plugins/ integrate authentication, telemetry/feature flags, MCP servers, language servers, and plugin loading.
- These services are pulled into the query/tool loop and the command/UI layers as needed.
10. Bridge and remote-control subsystem
- src/bridge/ is a bidirectional communication layer for IDE integrations and remote control.
- src/remote/, src/server/, and src/entrypoints/sdk/ support remote sessions, direct connect, and SDK-facing message adapters.
- This is a major architectural boundary separating the local terminal app from IDEs, remote sessions, and external clients.
11. Multi-agent and task orchestration
- src/coordinator/, src/tasks/, src/tools/AgentTool/, and swarm-related utilities enable multiple agents or background tasks to operate concurrently.
- The system distinguishes between local main-session work, shell tasks, remote agent tasks, in-process teammates, and dream/background tasks.
- Message passing, task status, and teammate state are first-class concepts.
12. Knowledge, memory, and context management
- src/memdir/, src/services/SessionMemory/, src/services/extractMemories/, and src/services/teamMemorySync/ manage persistent and team-shared memory.
- src/query/, src/context.ts, src/utils/context*, and compaction services control what context reaches the model.
- This layer is responsible for summarization, memory extraction, token budgeting, and context-window control.
13. Plugin and skill extensibility
- src/plugins/, src/services/plugins/, src/skills/, and src/utils/skills/ define the extension model.
- Plugins can contribute commands, tools, hooks, output styles, and marketplace behavior.
- Skills are reusable workflows that the model can invoke through the SkillTool, creating a second extensibility path beyond plugins.
14. Platform, shell, and local system integration
- src/utils/, src/ink/, src/keybindings/, src/vim/, and src/voice/ provide the platform substrate.
- This includes terminal rendering, input handling, shell parsing/execution, file-system and git helpers, keybinding resolution, vim mode, and optional voice input.
- These modules support the higher-level agent loop but are not themselves the conversation engine.
15. Data flow to draw in an architecture diagram
- User input enters the Ink UI or CLI command layer.
- The query engine packages context from state/history/memory, calls the model via API services, and interprets tool calls.
- Tool execution goes through permission checks and then into local system, remote, plugin, MCP, or bridge integrations.
- Results flow back into session state, message history, task trackers, and the UI for display and continued turns.
Main entry points: toolExecution.ts Tool Runtime · permissions.ts Permissions · App.tsx Ink App · commands Commands
Components 21
Runtime
App boot, orchestration, and execution loop
- Boot · CLI and app startup entrypoints
src/main.tsx - Query Engine · Drives model turns, tool loops, retries, and completion
src/QueryEngine.ts - Tool Contract · Shared tool and task abstractions for agent execution
src/Tool.ts - Task Core · Core task types and lifecycle coordination
src/Task.ts
Terminal UI
Ink screens, components, hooks, and interaction surfaces
Capabilities
Tool layer and user-facing command surface
- CLI Surface · Slash command registry and command handlers
src/commands.ts - Local Tools · Shell, files, search, notebook, and local environment tools
src/tools/BashTool/BashTool.tsx - Agent Tools · Subagents, skills, tasks, messaging, and planning tools
src/tools/AgentTool/AgentTool.tsx - Remote Tools · Web, MCP, remote triggers, and external resource tools
src/tools/WebFetchTool/WebFetchTool.ts - Commands · Session, config, review, diagnostics, plugins, memory, and remote commands
src/commands
State & Memory
Sessions, history, context, compaction, and persistence
- Session History · Conversation history, restore, resume, and durable session metadata
src/history.ts - Context Mgmt · Context selection, token budgeting, compaction, and memory shaping
src/query.ts - Memory Store · Memories, team memory sync, and extraction services
src/memdir/memdir.ts
Integrations
API, MCP, LSP, plugins, voice, and remote control
- API Services · Anthropic client, bootstrap, retries, usage, and telemetry-adjacent API glue
src/services/api/client.ts - Plugins & Skills · Plugin loading, marketplace, bundled skills, and skill hooks
src/services/plugins/PluginInstallationManager.ts - Bridge & Remote · IDE bridge, remote sessions, SDK adapters, and direct-connect control
src/bridge/bridgeMain.ts - LSP & MCP · Language-server and Model Context Protocol connectivity
src/services/lsp/LSPServerManager.ts
Platform
Shared utilities, permissions, shell, and runtime substrate
- Permissions · Permission prompts, policy rules, denial tracking, and approval flow
src/utils/permissions/permissions.ts - Tool Runtime · Streaming tool execution, orchestration, and hooks
src/services/tools/toolExecution.ts - Platform Substrate · Ink rendering, keybindings, shell, voice, and shared utilities
src/ink/ink.tsx
Connections 28
- Boot → Ink App: mounts · Bootstraps the terminal UI runtime
- Boot → CLI Surface: registers · Loads command handlers and startup features
- Ink App → UI State: uses · Renders from app state and reactive context
- Ink App → Query Engine: drives · User turns flow into model execution
- UI State → Session History: persists · Session state is reflected in conversation history
- Session History → Context Mgmt: feeds · History contributes to context assembly
- Memory Store → Context Mgmt: supplements · Long-lived memory is injected into model context
- Context Mgmt → Query Engine: packages · Prepares the prompt and token budget for the engine
- Query Engine → API Services: calls · Sends model requests and streams responses
- Query Engine → Tool Runtime: dispatches · Executes model-requested tool calls
- Tool Runtime → Permissions: checks · Requests approval for risky or privileged actions
- Permissions → Local Tools: gates · Shell and filesystem tools run through approval policy
- Permissions → Remote Tools: gates · Remote and web-facing tools are mediated by policy
- Permissions → Agent Tools: gates · Multi-agent and workflow tools require permission handling
- Tool Runtime → Local Tools: executes · Runs local environment and file operations
- Tool Runtime → Agent Tools: executes · Creates subagents, tasks, and skill-driven actions
- Tool Runtime → Remote Tools: executes · Handles web fetch, search, MCP, and remote triggers
- Tool Runtime → Plugins & Skills: extends · Plugin and skill logic contribute capabilities and hooks
- CLI Surface → Commands: implements · Command handlers orchestrate subsystems and sessions
- Commands → Ink App: opens · Many commands launch dialogs and screens in the UI
- Commands → Bridge & Remote: controls · Remote-control and bridge commands manage external sessions
- Commands → Plugins & Skills: manages · Commands expose plugin, marketplace, and skill management
- Bridge & Remote → API Services: adapts · Remote sessions and SDK messaging integrate with runtime services
- Bridge & Remote → UI State: syncs · Bridge events affect local app and session state
- LSP & MCP → Remote Tools: backs · MCP and LSP power model-facing external capabilities
- Platform Substrate → Ink App: renders · Ink and terminal primitives back the UI layer
- Platform Substrate → Permissions: supports · Shared helpers and input plumbing support approvals
- Platform Substrate → Tool Runtime: supports · Shared process, shell, and utility code underpins tool execution