# leeyeel/claude-code architecture

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

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

## Overview

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: [`src/services/tools/toolExecution.ts`](https://github.com/leeyeel/claude-code/blob/main/src/services/tools/toolExecution.ts) (Tool Runtime), [`src/utils/permissions/permissions.ts`](https://github.com/leeyeel/claude-code/blob/main/src/utils/permissions/permissions.ts) (Permissions), [`src/components/App.tsx`](https://github.com/leeyeel/claude-code/blob/main/src/components/App.tsx) (Ink App), [`src/commands`](https://github.com/leeyeel/claude-code/tree/main/src/commands) (Commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Boot<br/>entrypoint<br/>[main.tsx]"]
  node_query_engine["Query Engine<br/>orchestrator<br/>[QueryEngine.ts]"]
  node_tool_contract["Tool Contract<br/>runtime contract<br/>[Tool.ts]"]
  node_task_core["Task Core<br/>task model<br/>[Task.ts]"]
end

subgraph group_ui["Terminal UI"]
  node_ui_app["Ink App<br/>terminal ui<br/>[App.tsx]"]
  node_ui_state["UI State<br/>react state<br/>[AppState.tsx]"]
end

subgraph group_capabilities["Capabilities"]
  node_cli_surface["CLI Surface<br/>command shell<br/>[commands.ts]"]
  node_local_tools["Local Tools<br/>tool set<br/>[BashTool.tsx]"]
  node_agent_tools["Agent Tools<br/>tool set<br/>[AgentTool.tsx]"]
  node_remote_tools["Remote Tools<br/>tool set<br/>[WebFetchTool.ts]"]
  node_commands_subsystem["Commands<br/>command set"]
end

subgraph group_data["State & Memory"]
  node_history_session["Session History<br/>session state<br/>[history.ts]"]
  node_context_mgmt["Context Mgmt<br/>context pipeline<br/>[query.ts]"]
  node_memory_store["Memory Store<br/>persistent memory<br/>[memdir.ts]"]
end

subgraph group_integrations["Integrations"]
  node_api_services["API Services<br/>integration<br/>[client.ts]"]
  node_plugins_skills["Plugins & Skills<br/>extensibility"]
  node_bridge_remote["Bridge & Remote<br/>integration boundary<br/>[bridgeMain.ts]"]
  node_lsp_mcp["LSP & MCP<br/>integration"]
end

subgraph group_platform["Platform"]
  node_permission_layer["Permissions<br/>safety boundary<br/>[permissions.ts]"]
  node_tool_runtime["Tool Runtime<br/>execution engine<br/>[toolExecution.ts]"]
  node_platform_runtime["Platform Substrate<br/>runtime substrate<br/>[ink.tsx]"]
end

node_main -->|"mounts"| node_ui_app
node_main -->|"registers"| node_cli_surface
node_ui_app -->|"uses"| node_ui_state
node_ui_app -->|"drives"| node_query_engine
node_ui_state -->|"persists"| node_history_session
node_history_session -->|"feeds"| node_context_mgmt
node_memory_store -->|"supplements"| node_context_mgmt
node_context_mgmt -->|"packages"| node_query_engine
node_query_engine -->|"calls"| node_api_services
node_query_engine -->|"dispatches"| node_tool_runtime
node_tool_runtime -->|"checks"| node_permission_layer
node_permission_layer -->|"gates"| node_local_tools
node_permission_layer -->|"gates"| node_remote_tools
node_permission_layer -->|"gates"| node_agent_tools
node_tool_runtime -->|"executes"| node_local_tools
node_tool_runtime -->|"executes"| node_agent_tools
node_tool_runtime -->|"executes"| node_remote_tools
node_tool_runtime -->|"extends"| node_plugins_skills
node_cli_surface -->|"implements"| node_commands_subsystem
node_commands_subsystem -->|"opens"| node_ui_app
node_commands_subsystem -->|"controls"| node_bridge_remote
node_commands_subsystem -->|"manages"| node_plugins_skills
node_bridge_remote -->|"adapts"| node_api_services
node_bridge_remote -->|"syncs"| node_ui_state
node_lsp_mcp -->|"backs"| node_remote_tools
node_platform_runtime -->|"renders"| node_ui_app
node_platform_runtime -->|"supports"| node_permission_layer
node_platform_runtime -->|"supports"| node_tool_runtime

click node_main "https://github.com/leeyeel/claude-code/blob/main/src/main.tsx"
click node_query_engine "https://github.com/leeyeel/claude-code/blob/main/src/QueryEngine.ts"
click node_tool_contract "https://github.com/leeyeel/claude-code/blob/main/src/Tool.ts"
click node_task_core "https://github.com/leeyeel/claude-code/blob/main/src/Task.ts"
click node_cli_surface "https://github.com/leeyeel/claude-code/blob/main/src/commands.ts"
click node_ui_app "https://github.com/leeyeel/claude-code/blob/main/src/components/App.tsx"
click node_ui_state "https://github.com/leeyeel/claude-code/blob/main/src/state/AppState.tsx"
click node_history_session "https://github.com/leeyeel/claude-code/blob/main/src/history.ts"
click node_context_mgmt "https://github.com/leeyeel/claude-code/blob/main/src/query.ts"
click node_memory_store "https://github.com/leeyeel/claude-code/blob/main/src/memdir/memdir.ts"
click node_permission_layer "https://github.com/leeyeel/claude-code/blob/main/src/utils/permissions/permissions.ts"
click node_tool_runtime "https://github.com/leeyeel/claude-code/blob/main/src/services/tools/toolExecution.ts"
click node_local_tools "https://github.com/leeyeel/claude-code/blob/main/src/tools/BashTool/BashTool.tsx"
click node_agent_tools "https://github.com/leeyeel/claude-code/blob/main/src/tools/AgentTool/AgentTool.tsx"
click node_remote_tools "https://github.com/leeyeel/claude-code/blob/main/src/tools/WebFetchTool/WebFetchTool.ts"
click node_commands_subsystem "https://github.com/leeyeel/claude-code/tree/main/src/commands"
click node_api_services "https://github.com/leeyeel/claude-code/blob/main/src/services/api/client.ts"
click node_plugins_skills "https://github.com/leeyeel/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts"
click node_bridge_remote "https://github.com/leeyeel/claude-code/blob/main/src/bridge/bridgeMain.ts"
click node_lsp_mcp "https://github.com/leeyeel/claude-code/blob/main/src/services/lsp/LSPServerManager.ts"
click node_platform_runtime "https://github.com/leeyeel/claude-code/blob/main/src/ink/ink.tsx"

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_query_engine,node_tool_contract,node_task_core toneBlue
class node_ui_app,node_ui_state toneAmber
class node_cli_surface,node_local_tools,node_agent_tools,node_remote_tools,node_commands_subsystem toneMint
class node_history_session,node_context_mgmt,node_memory_store toneRose
class node_api_services,node_plugins_skills,node_bridge_remote,node_lsp_mcp toneIndigo
class node_permission_layer,node_tool_runtime,node_platform_runtime toneTeal
```

## Components

### Runtime

App boot, orchestration, and execution loop

- [Boot](https://github.com/leeyeel/claude-code/blob/main/src/main.tsx): entrypoint · CLI and app startup entrypoints · `src/main.tsx`
- [Query Engine](https://github.com/leeyeel/claude-code/blob/main/src/QueryEngine.ts): orchestrator · Drives model turns, tool loops, retries, and completion · `src/QueryEngine.ts`
- [Tool Contract](https://github.com/leeyeel/claude-code/blob/main/src/Tool.ts): runtime contract · Shared tool and task abstractions for agent execution · `src/Tool.ts`
- [Task Core](https://github.com/leeyeel/claude-code/blob/main/src/Task.ts): task model · Core task types and lifecycle coordination · `src/Task.ts`

### Terminal UI

Ink screens, components, hooks, and interaction surfaces

- [Ink App](https://github.com/leeyeel/claude-code/blob/main/src/components/App.tsx): terminal ui · Terminal React app and full-screen screens · `src/components/App.tsx`
- [UI State](https://github.com/leeyeel/claude-code/blob/main/src/state/AppState.tsx): react state · App state store, context, hooks, and interaction wiring · `src/state/AppState.tsx`

### Capabilities

Tool layer and user-facing command surface

- [CLI Surface](https://github.com/leeyeel/claude-code/blob/main/src/commands.ts): command shell · Slash command registry and command handlers · `src/commands.ts`
- [Local Tools](https://github.com/leeyeel/claude-code/blob/main/src/tools/BashTool/BashTool.tsx): tool set · Shell, files, search, notebook, and local environment tools · `src/tools/BashTool/BashTool.tsx`
- [Agent Tools](https://github.com/leeyeel/claude-code/blob/main/src/tools/AgentTool/AgentTool.tsx): tool set · Subagents, skills, tasks, messaging, and planning tools · `src/tools/AgentTool/AgentTool.tsx`
- [Remote Tools](https://github.com/leeyeel/claude-code/blob/main/src/tools/WebFetchTool/WebFetchTool.ts): tool set · Web, MCP, remote triggers, and external resource tools · `src/tools/WebFetchTool/WebFetchTool.ts`
- [Commands](https://github.com/leeyeel/claude-code/tree/main/src/commands): command set · Session, config, review, diagnostics, plugins, memory, and remote commands · `src/commands`

### State & Memory

Sessions, history, context, compaction, and persistence

- [Session History](https://github.com/leeyeel/claude-code/blob/main/src/history.ts): session state · Conversation history, restore, resume, and durable session metadata · `src/history.ts`
- [Context Mgmt](https://github.com/leeyeel/claude-code/blob/main/src/query.ts): context pipeline · Context selection, token budgeting, compaction, and memory shaping · `src/query.ts`
- [Memory Store](https://github.com/leeyeel/claude-code/blob/main/src/memdir/memdir.ts): persistent memory · Memories, team memory sync, and extraction services · `src/memdir/memdir.ts`

### Integrations

API, MCP, LSP, plugins, voice, and remote control

- [API Services](https://github.com/leeyeel/claude-code/blob/main/src/services/api/client.ts): integration · Anthropic client, bootstrap, retries, usage, and telemetry-adjacent API glue · `src/services/api/client.ts`
- [Plugins & Skills](https://github.com/leeyeel/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts): extensibility · Plugin loading, marketplace, bundled skills, and skill hooks · `src/services/plugins/PluginInstallationManager.ts`
- [Bridge & Remote](https://github.com/leeyeel/claude-code/blob/main/src/bridge/bridgeMain.ts): integration boundary · IDE bridge, remote sessions, SDK adapters, and direct-connect control · `src/bridge/bridgeMain.ts`
- [LSP & MCP](https://github.com/leeyeel/claude-code/blob/main/src/services/lsp/LSPServerManager.ts): integration · Language-server and Model Context Protocol connectivity · `src/services/lsp/LSPServerManager.ts`

### Platform

Shared utilities, permissions, shell, and runtime substrate

- [Permissions](https://github.com/leeyeel/claude-code/blob/main/src/utils/permissions/permissions.ts): safety boundary · Permission prompts, policy rules, denial tracking, and approval flow · `src/utils/permissions/permissions.ts`
- [Tool Runtime](https://github.com/leeyeel/claude-code/blob/main/src/services/tools/toolExecution.ts): execution engine · Streaming tool execution, orchestration, and hooks · `src/services/tools/toolExecution.ts`
- [Platform Substrate](https://github.com/leeyeel/claude-code/blob/main/src/ink/ink.tsx): runtime substrate · Ink rendering, keybindings, shell, voice, and shared utilities · `src/ink/ink.tsx`

## Connections

- 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
