How zackautocracy/claude-code works
1. What this repository is
- This is the source snapshot for a terminal-based agentic CLI: Claude Code.
- The architecture centers on a single interactive session loop that collects context, sends it to the model, receives tool calls or text, executes tools, and renders everything in a React/Ink terminal UI.
- The codebase is TypeScript on Bun, with React + Ink for terminal rendering.
2. Top-level runtime shape
- Startup flows through src/main.tsx, src/entrypoints/cli.tsx, and related entrypoints.
- The app bootstraps configuration, auth, keychain/secure storage, feature flags, and UI state before entering the main loop.
- There are multiple entry modes beyond the normal CLI: REPL, resume, MCP/server integrations, and bridge/remote modes.
3. Core orchestration layer
- QueryEngine.ts, Tool.ts, and Task.ts are the central abstractions for the agent loop.
- QueryEngine drives model requests, streaming responses, retries, tool-use loops, and token/cost tracking.
- Tool.ts defines the contract for tool inputs, permissions, progress, and result handling; tools are pluggable execution units rather than ad hoc functions.
- Task.ts models ongoing work items and lets the UI and services track long-running work separately from a single model turn.
4. Command system
- src/commands/ contains the user-facing slash commands such as config, login/logout, review, compact, memory, tasks, mcp, resume, diff, and diagnostics.
- src/commands.ts acts as the command registry and dispatch layer.
- Commands are part of the terminal UX and also mutate persistent state, trigger services, or open dialogs/screens; they are not just text macros.
5. Tool execution subsystem
- src/tools/ is the largest functional boundary in the repo: each tool is a self-contained module with its prompt contract, UI, schema, and execution logic.
- Tools cover file operations, shell execution, search, web access, LSP, notebooks, sub-agents, tasks, messaging, planning/worktree mode, MCP access, and remote triggers.
- The execution path is: model requests a tool → permission layer evaluates it → tool-specific service runs it → result is rendered back into the conversation and/or task stream.
6. Permission and safety boundary
- Tool use is gated by src/hooks/toolPermission/ and the broader permission utilities under src/utils/permissions/.
- This boundary decides whether a tool call is auto-approved, denied, or surfaced as an interactive prompt.
- The repo also has command/path/shell validation, sandbox decisions, and destructive-action warnings, which are especially important around shell, file write/edit, and PowerShell/Bash tools.
- In architecture terms, this is the main control plane that separates “model intent” from “host-side side effects.”
7. UI and interaction layer
- The user interface is built from src/components/, src/screens/, src/ink/, and src/keybindings/.
- src/ink/ is a custom terminal rendering layer wrapping Ink-like behavior, input handling, layout, and screen updates.
- Components implement the chat transcript, permission dialogs, tool result views, task panels, settings, onboarding, diffs, and modal flows.
- Keybindings and vim mode are first-class input subsystems rather than simple terminal shortcuts.
8. State, session history, and persistence
- Application state lives in src/state/, with selectors and store helpers for session state, UI state, queued messages, overlays, and notifications.
- src/assistant/sessionHistory.ts, src/history.ts, src/sessionStorage*, and related utilities persist conversation/session data.
- Memory is a separate persistence concept via src/memdir/ and src/services/SessionMemory/, supporting long-lived context beyond a single transcript.
- This means the product has at least three state planes: transient UI state, session transcript state, and durable memory/config state.
9. Services and external integrations
- src/services/ contains the integration layer for Anthropic API access, OAuth/auth, analytics, plugins, LSP, MCP, compacting, memory extraction, and remote-managed settings.
- src/services/api/ is the outbound API boundary for Claude-related network calls and internal backend endpoints.
- src/services/mcp/ manages Model Context Protocol connections and remote tool servers.
- src/services/lsp/ provides language-server orchestration for code intelligence.
- src/services/plugins/ loads and manages plugin behavior, while src/services/analytics/ and telemetry utilities handle instrumentation.
10. Bridge, remote, and desktop control paths
- src/bridge/, src/remote/, src/server/, and src/upstreamproxy/ support non-local or externally controlled sessions.
- The bridge layer connects the CLI to IDE extensions and remote-control surfaces, with explicit messaging, permission callbacks, session identifiers, and transport handling.
- src/remote/ and src/server/ manage remote sessions and direct-connect style flows.
- This is a key architectural boundary: it separates local terminal interaction from IDE/remote/session orchestration concerns.
11. Multi-agent and teamwork model
- The repo treats agents as a first-class abstraction: src/tools/AgentTool/, src/coordinator/, src/tasks/, src/utils/swarm/, and team-related components all support parallel work.
- Sub-agents, coordinator mode, in-process teammates, remote agents, and task messaging are separate concepts, not synonyms.
- The architecture supports spawning, monitoring, resuming, and messaging across workers, with permission propagation and layout/state handling for these concurrent sessions.
12. Skills, plugins, and extensibility
- src/skills/ and src/tools/SkillTool/ implement reusable workflows that can be bundled or loaded from disk.
- src/plugins/ and src/utils/plugins/ implement discovery, installation, validation, loading, marketplace management, and startup checks for plugins.
- src/tools/MCPTool/ and the MCP services extend the system with externally hosted capabilities.
- These extension systems are separate from core tools: they let the product grow without hardcoding every workflow into the core loop.
13. Supporting infrastructure: config, migrations, and policy
- src/utils/settings/, src/schemas/, and src/migrations/ manage config validation, backward compatibility, and settings evolution.
- Policy and limit handling appear across src/services/policyLimits/, src/constants/, and permission/rate-limit utilities.
- This indicates the app is designed for long-lived local installation with evolving settings and managed enterprise constraints.
14. Data flow to diagram
- The clearest architecture diagram would show: terminal input/UI → session state/command parsing → QueryEngine → permissions/tools/services → model/API or local side effects → streamed results back to UI.
- Side channels branch into persistence/memory, telemetry/analytics, remote/bridge/MCP integrations, and task/agent orchestration.
- The important boundary lines are: UI vs. execution, model intent vs. permissioned side effect, local session vs. remote/bridge sessions, and core loop vs. extensibility layers.
Main entry points: tools Tools · state App state · QueryEngine.ts Query engine · cli.tsx CLI entry
Components 21
Runtime
Startup, entrypoints, and the main agent loop.
UI
Terminal rendering, screens, commands, and interaction surfaces.
- Slash cmds · Command registry and dispatch for user-facing slash commands.
src/commands.ts - Screens · React/Ink screens and dialogs for chat, settings, diffs, onboarding, and prompts.
src/components - Ink layer · Custom terminal rendering, input handling, and layout primitives.
src/ink - Keybinds · Shortcut resolution, bindings, and vim-mode input handling.
src/keybindings
Execution
Model orchestration, tools, permissions, tasks, and side effects.
- Query engine · Drives model turns, streaming, retries, and tool loops.
src/QueryEngine.ts - Tool contract · Shared tool interface for inputs, permissions, progress, and results.
src/Tool.ts - Task model · Represents long-running work tracked alongside turns.
src/Task.ts - Permissions · Tool approval, safety rules, and host-side side-effect gating.
src/hooks/toolPermission - Tools · Pluggable file, shell, search, web, LSP, MCP, agent, and task tools.
src/tools - Swarm · Parallel teammate and sub-agent orchestration utilities.
src/utils/swarm
Integrations
Remote control, MCP, API, and external connectivity.
- Services · API, auth, analytics, LSP, compacting, and memory services.
src/services - Bridge · IDE/remote bridge messaging, permissions, and session transport.
src/bridge - Remote · Remote sessions, direct connect, and websocket session management.
src/remote - MCP · Model Context Protocol connections and remote tool servers.
src/services/mcp
State
Session history, app state, memory, and persistence.
Connections 25
- Entry → CLI entry: starts · Bootstraps CLI runtime and mode selection.
- CLI entry → App state: initializes · Loads application state and session UI state.
- CLI entry → Services: configures · Sets up auth, feature flags, model access, and integrations.
- CLI entry → Ink layer: renders · Starts the terminal UI rendering stack.
- Ink layer → Screens: hosts · UI screens and dialogs are rendered through Ink.
- Keybinds → Screens: drives · Keyboard input routes into interactive UI surfaces.
- Slash cmds → Screens: opens · Commands trigger dialogs, screens, and terminal flows.
- Slash cmds → App state: mutates · Commands update persistent and transient app state.
- Query engine → Tool contract: invokes · Model turns request tools through the shared tool contract.
- Query engine → Permissions: checks · Tool calls are gated by permission and safety rules.
- Query engine → Services: calls · Uses model/API, compaction, memory, and other services.
- Tools → Services: delegates · Tools rely on shared services for execution and integrations.
- Tools → Permissions: requests · Tool execution is approved or denied by the permission layer.
- Tools → Task model: reports · Long-running work is surfaced as tasks and progress items.
- Tools → Swarm: spawns · Agent tools and teammate flows create concurrent workers.
- Query engine → App state: reads/writes · Tracks session state, queued messages, and turn progress.
- App state → History: persists · Session transcript and resume data are stored durably.
- App state → Memory: stores · Long-lived memory is maintained separately from chat history.
- Services → MCP: adapts · Service layer manages MCP clients and remote tool servers.
- Bridge → Remote: transports · Bridge and remote paths carry session control and messaging.
- Bridge → Permissions: propagates · Remote control paths forward permission callbacks and trust state.
- Plugins → Slash cmds: extends · Plugins can contribute commands and UI flows.
- Plugins → Tools: extends · Plugins can add tool behavior and integrations.
- Skills → Tools: reuses · Skills package repeatable workflows used by tools and agents.
- Swarm → App state: coordinates · Multi-agent sessions share task and teammate state.