# zackautocracy/claude-code architecture

> Architecture diagram of the GitHub repository zackautocracy/claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zackautocracy/claude-code
- Repository: https://github.com/zackautocracy/claude-code

## Overview

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: [`src/tools`](https://github.com/zackautocracy/claude-code/tree/main/src/tools) (Tools), [`src/state`](https://github.com/zackautocracy/claude-code/tree/main/src/state) (App state), [`src/QueryEngine.ts`](https://github.com/zackautocracy/claude-code/blob/main/src/QueryEngine.ts) (Query engine), [`src/entrypoints/cli.tsx`](https://github.com/zackautocracy/claude-code/blob/main/src/entrypoints/cli.tsx) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Entry<br/>bootstrap<br/>[main.tsx]"]
  node_cli["CLI entry<br/>entrypoint<br/>[cli.tsx]"]
end

subgraph group_ui["UI"]
  node_commands["Slash cmds<br/>command-registry<br/>[commands.ts]"]
  node_screens["Screens<br/>terminal-ui"]
  node_ink["Ink layer<br/>rendering"]
  node_keybindings["Keybinds<br/>input"]
end

subgraph group_execution["Execution"]
  node_queryengine["Query engine<br/>orchestrator<br/>[QueryEngine.ts]"]
  node_toolbase["Tool contract<br/>abstraction<br/>[Tool.ts]"]
  node_taskbase["Task model<br/>work-item<br/>[Task.ts]"]
  node_permission["Permissions<br/>control-plane"]
  node_tools["Tools"]
  node_swarm["Swarm<br/>multi-agent"]
end

subgraph group_integrations["Integrations"]
  node_services["Services<br/>integrations"]
  node_bridge["Bridge<br/>remote-control"]
  node_remote["Remote<br/>session-routing"]
  node_mcp["MCP<br/>protocol-adapter"]
end

subgraph group_state["State"]
  node_state[("App state<br/>store")]
  node_history[("History<br/>session-store<br/>[history.ts]")]
  node_memory[("Memory<br/>durable-context")]
end

subgraph group_extensibility["Extensibility"]
  node_plugins["Plugins<br/>extension-host"]
  node_skills["Skills<br/>workflow-packages"]
end

node_main -->|"starts"| node_cli
node_cli -->|"initializes"| node_state
node_cli -->|"configures"| node_services
node_cli -->|"renders"| node_ink
node_ink -->|"hosts"| node_screens
node_keybindings -->|"drives"| node_screens
node_commands -->|"opens"| node_screens
node_commands -->|"mutates"| node_state
node_queryengine -->|"invokes"| node_toolbase
node_queryengine -->|"checks"| node_permission
node_queryengine -->|"calls"| node_services
node_tools -->|"delegates"| node_services
node_tools -->|"requests"| node_permission
node_tools -->|"reports"| node_taskbase
node_tools -->|"spawns"| node_swarm
node_queryengine -->|"reads/writes"| node_state
node_state -->|"persists"| node_history
node_state -->|"stores"| node_memory
node_services -->|"adapts"| node_mcp
node_bridge -->|"transports"| node_remote
node_bridge -->|"propagates"| node_permission
node_plugins -->|"extends"| node_commands
node_plugins -->|"extends"| node_tools
node_skills -->|"reuses"| node_tools
node_swarm -->|"coordinates"| node_state

click node_main "https://github.com/zackautocracy/claude-code/blob/main/src/main.tsx"
click node_cli "https://github.com/zackautocracy/claude-code/blob/main/src/entrypoints/cli.tsx"
click node_queryengine "https://github.com/zackautocracy/claude-code/blob/main/src/QueryEngine.ts"
click node_toolbase "https://github.com/zackautocracy/claude-code/blob/main/src/Tool.ts"
click node_taskbase "https://github.com/zackautocracy/claude-code/blob/main/src/Task.ts"
click node_permission "https://github.com/zackautocracy/claude-code/tree/main/src/hooks/toolPermission"
click node_tools "https://github.com/zackautocracy/claude-code/tree/main/src/tools"
click node_commands "https://github.com/zackautocracy/claude-code/blob/main/src/commands.ts"
click node_screens "https://github.com/zackautocracy/claude-code/tree/main/src/components"
click node_ink "https://github.com/zackautocracy/claude-code/tree/main/src/ink"
click node_keybindings "https://github.com/zackautocracy/claude-code/tree/main/src/keybindings"
click node_state "https://github.com/zackautocracy/claude-code/tree/main/src/state"
click node_history "https://github.com/zackautocracy/claude-code/blob/main/src/history.ts"
click node_memory "https://github.com/zackautocracy/claude-code/tree/main/src/memdir"
click node_services "https://github.com/zackautocracy/claude-code/tree/main/src/services"
click node_bridge "https://github.com/zackautocracy/claude-code/tree/main/src/bridge"
click node_remote "https://github.com/zackautocracy/claude-code/tree/main/src/remote"
click node_mcp "https://github.com/zackautocracy/claude-code/tree/main/src/services/mcp"
click node_plugins "https://github.com/zackautocracy/claude-code/tree/main/src/services/plugins"
click node_skills "https://github.com/zackautocracy/claude-code/tree/main/src/skills"
click node_swarm "https://github.com/zackautocracy/claude-code/tree/main/src/utils/swarm"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli toneBlue
class node_commands,node_screens,node_ink,node_keybindings toneAmber
class node_queryengine,node_toolbase,node_taskbase,node_permission,node_tools,node_swarm toneMint
class node_services,node_bridge,node_remote,node_mcp toneRose
class node_state,node_history,node_memory toneIndigo
class node_plugins,node_skills toneTeal
```

## Components

### Runtime

Startup, entrypoints, and the main agent loop.

- [Entry](https://github.com/zackautocracy/claude-code/blob/main/src/main.tsx): bootstrap · CLI startup and runtime bootstrap. · `src/main.tsx`
- [CLI entry](https://github.com/zackautocracy/claude-code/blob/main/src/entrypoints/cli.tsx): entrypoint · Command-line entrypoints and mode selection. · `src/entrypoints/cli.tsx`

### UI

Terminal rendering, screens, commands, and interaction surfaces.

- [Slash cmds](https://github.com/zackautocracy/claude-code/blob/main/src/commands.ts): command-registry · Command registry and dispatch for user-facing slash commands. · `src/commands.ts`
- [Screens](https://github.com/zackautocracy/claude-code/tree/main/src/components): terminal-ui · React/Ink screens and dialogs for chat, settings, diffs, onboarding, and prompts. · `src/components`
- [Ink layer](https://github.com/zackautocracy/claude-code/tree/main/src/ink): rendering · Custom terminal rendering, input handling, and layout primitives. · `src/ink`
- [Keybinds](https://github.com/zackautocracy/claude-code/tree/main/src/keybindings): input · Shortcut resolution, bindings, and vim-mode input handling. · `src/keybindings`

### Execution

Model orchestration, tools, permissions, tasks, and side effects.

- [Query engine](https://github.com/zackautocracy/claude-code/blob/main/src/QueryEngine.ts): orchestrator · Drives model turns, streaming, retries, and tool loops. · `src/QueryEngine.ts`
- [Tool contract](https://github.com/zackautocracy/claude-code/blob/main/src/Tool.ts): abstraction · Shared tool interface for inputs, permissions, progress, and results. · `src/Tool.ts`
- [Task model](https://github.com/zackautocracy/claude-code/blob/main/src/Task.ts): work-item · Represents long-running work tracked alongside turns. · `src/Task.ts`
- [Permissions](https://github.com/zackautocracy/claude-code/tree/main/src/hooks/toolPermission): control-plane · Tool approval, safety rules, and host-side side-effect gating. · `src/hooks/toolPermission`
- [Tools](https://github.com/zackautocracy/claude-code/tree/main/src/tools): toolset · Pluggable file, shell, search, web, LSP, MCP, agent, and task tools. · `src/tools`
- [Swarm](https://github.com/zackautocracy/claude-code/tree/main/src/utils/swarm): multi-agent · Parallel teammate and sub-agent orchestration utilities. · `src/utils/swarm`

### Integrations

Remote control, MCP, API, and external connectivity.

- [Services](https://github.com/zackautocracy/claude-code/tree/main/src/services): integrations · API, auth, analytics, LSP, compacting, and memory services. · `src/services`
- [Bridge](https://github.com/zackautocracy/claude-code/tree/main/src/bridge): remote-control · IDE/remote bridge messaging, permissions, and session transport. · `src/bridge`
- [Remote](https://github.com/zackautocracy/claude-code/tree/main/src/remote): session-routing · Remote sessions, direct connect, and websocket session management. · `src/remote`
- [MCP](https://github.com/zackautocracy/claude-code/tree/main/src/services/mcp): protocol-adapter · Model Context Protocol connections and remote tool servers. · `src/services/mcp`

### State

Session history, app state, memory, and persistence.

- [App state](https://github.com/zackautocracy/claude-code/tree/main/src/state): store · Transient UI state, overlays, queued messages, and selectors. · `src/state`
- [History](https://github.com/zackautocracy/claude-code/blob/main/src/history.ts): session-store · Conversation/session persistence and resume support. · `src/history.ts`
- [Memory](https://github.com/zackautocracy/claude-code/tree/main/src/memdir): durable-context · Long-lived memory and extracted context beyond a single transcript. · `src/memdir`

### Extensibility

Plugins, skills, and reusable agent workflows.

- [Plugins](https://github.com/zackautocracy/claude-code/tree/main/src/services/plugins): extension-host · Plugin discovery, validation, installation, and loading. · `src/services/plugins`
- [Skills](https://github.com/zackautocracy/claude-code/tree/main/src/skills): workflow-packages · Reusable workflows and bundled skill definitions. · `src/skills`

## Connections

- 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.
