# alesha-pro/claude-code architecture

> Architecture diagram of the GitHub repository alesha-pro/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/alesha-pro/claude-code
- Repository: https://github.com/alesha-pro/claude-code

## Overview

1. **Overall shape**
   - This is a Bun + TypeScript CLI application built around a terminal React UI (Ink). The architecture centers on an interactive session loop that takes user input, routes it through a command/tool system, talks to Anthropic’s API, and renders updates back into the terminal.

2. **Startup and bootstrap**
   - `src/main.tsx`, `src/entrypoints/`, `src/setup.ts`, and `src/bootstrap/` form the launch path.
   - Startup does more than parse CLI args: it preloads settings, auth, feature flags, and environment state so the interactive session can begin quickly.
   - `src/screens/` contains top-level modes like REPL, doctor, and resume-conversation screens.

3. **Core conversation engine**
   - `src/QueryEngine.ts` is the central orchestration layer for model interactions.
   - It handles streaming responses, tool-call loops, retries, token accounting, and conversation state transitions.
   - Supporting modules in `src/query/`, `src/context.ts`, `src/history.ts`, and `src/cost-tracker.ts` feed the engine prompt context, budgets, and prior turns.

4. **Command layer**
   - `src/commands.ts` and `src/commands/**` implement slash commands such as `/commit`, `/compact`, `/mcp`, `/config`, `/resume`, `/tasks`, and `/memory`.
   - Commands are a user-facing control plane for session management, environment inspection, and workflow shortcuts.
   - They usually mutate app state, open dialogs, or trigger services rather than directly performing model inference.

5. **Tool execution layer**
   - `src/tools.ts` and `src/tools/**` define the agent’s action surface: shell, file read/write/edit, search, web fetch/search, MCP, LSP, agent spawning, task ops, plan/worktree toggles, and remote triggers.
   - Tools are strongly typed and each has its own permission model, UI, and execution logic.
   - Tool calls are the main data path from model output to real-world side effects.

6. **Permission and policy boundary**
   - `src/hooks/toolPermission/`, `src/components/permissions/`, and `src/utils/permissions/` enforce the security boundary around tool usage.
   - Every potentially dangerous tool invocation passes through permission checks, policy rules, and sometimes classifier-based decisions.
   - The UI layer can prompt the user, while noninteractive modes and auto modes resolve permissions through configured policy.

7. **Terminal UI, state, and interaction**
   - The main user experience lives in `src/components/`, `src/state/`, `src/context/`, `src/hooks/`, and the custom `src/ink/` renderer wrapper.
   - Ink/React components render the prompt, message stream, diffs, dialogs, status lines, and task panels.
   - Global state and contexts coordinate the live session, notifications, overlays, queued messages, and terminal behaviors.

8. **External service integrations**
   - `src/services/` contains the outbound integrations: Anthropic API client, OAuth, analytics, telemetry, rate limits, policy limits, and remote settings.
   - This layer is the boundary to cloud services and persists or fetches data needed for auth, usage tracking, feature rollout, and organization policy.
   - It also includes compacting, memory extraction, and token estimation services that shape what gets sent to the model.

9. **IDE and bridge subsystem**
   - `src/bridge/` implements bidirectional communication with external editors, especially VS Code and JetBrains.
   - The bridge handles messaging, permissions callbacks, session creation, REPL bridging, JWT auth, and status reporting.
   - Architecturally, this is a separate control plane that lets the CLI session be driven or mirrored from an IDE environment.

10. **Remote, server, and transport paths**
    - `src/remote/`, `src/server/`, `src/upstreamproxy/`, and `src/cli/transports/` handle non-local session flows.
    - These modules support remote sessions, websocket/SSE/WebSocket-like transport abstraction, direct-connect sessions, and proxying to upstream services.
    - They form the boundary for background or distributed execution rather than the local interactive terminal loop.

11. **Multi-agent, tasks, and coordination**
    - `src/coordinator/`, `src/tasks/`, `src/tools/AgentTool/`, and `src/tools/Task*` implement parallel or delegated work.
    - Agents can spawn sub-agents, create/update/list tasks, send messages, and operate in coordinated or swarm-like modes.
    - The task subsystem provides a durable view of background work separate from the main chat transcript.

12. **Memory, compacting, and long-running context**
    - `src/memdir/`, `src/services/compact/`, `src/services/SessionMemory/`, and `src/services/extractMemories/` manage persistence and context reduction.
    - These subsystems preserve useful facts across sessions, extract memories from turns, and compress long conversations when token pressure rises.
    - This is a key data-flow boundary: raw interaction history is distilled into smaller, persistent artifacts.

13. **Plugins, skills, MCP, and extensibility**
    - `src/plugins/`, `src/skills/`, `src/services/mcp/`, `src/components/mcp/`, and the MCP-related tools expose extension points.
    - Plugins contribute commands, tools, output styles, and startup checks; skills package reusable workflows; MCP connects to external tool servers.
    - This is the main extensibility layer for adding capabilities without changing the core app.

14. **Supporting subsystems**
    - `src/keybindings/`, `src/vim/`, `src/voice/`, `src/buddy/`, `src/outputStyles/`, `src/migrations/`, and `src/schemas/` are auxiliary but important.
    - They handle input modalities, visual mode, voice features, easter-egg UI, migration of persisted settings, and schema validation.
    - `src/utils/` is the shared foundation: shell parsing, filesystem helpers, auth, git, telemetry, terminal ops, and many protocol adapters.

15. **Primary architectural flow**
    - The typical flow is: user input → command or prompt processing → permission/policy evaluation → query engine / tool execution → external service or local side effect → UI update + history/state persistence.
    - Most subsystems exist to support one of those transitions: collecting context, enforcing safety, rendering state, or bridging to external systems.

Main entry points: [`src/QueryEngine.ts`](https://github.com/alesha-pro/claude-code/blob/main/src/QueryEngine.ts) (QueryEngine), [`src/services`](https://github.com/alesha-pro/claude-code/tree/main/src/services) (services), [`src/tools.ts`](https://github.com/alesha-pro/claude-code/blob/main/src/tools.ts) (tools), [`src/components`](https://github.com/alesha-pro/claude-code/tree/main/src/components) (components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_boot["Boot & entry"]
  node_main["main<br/>entrypoint<br/>[main.tsx]"]
  node_entrypoints["entrypoints<br/>cli boot"]
  node_setup["setup<br/>startup init<br/>[setup.ts]"]
  node_screens["screens<br/>modes"]
end

subgraph group_grp_core["Session core"]
  node_queryengine["QueryEngine<br/>orchestrator<br/>[QueryEngine.ts]"]
  node_querymods["query ctx<br/>prompt state"]
  node_context["context<br/>[context.ts]"]
end

subgraph group_grp_ui["Terminal UI"]
  node_appstate[("App state<br/>session store")]
  node_components["components<br/>ink ui"]
  node_ink["ink<br/>renderer"]
  node_hooks["hooks"]
end

subgraph group_grp_tools["Tools & commands"]
  node_commands["commands<br/>slash cmds<br/>[commands.ts]"]
  node_toolregistry["tools<br/>[tools.ts]"]
  node_toolimpls["tool impls<br/>tool modules"]
end

subgraph group_grp_policy["Policy & permissions"]
  node_permhooks["permission hooks<br/>approval flow"]
  node_permui["permission UI<br/>approval dialogs"]
  node_permutils["permission utils<br/>policy rules"]
end

subgraph group_grp_services["Services"]
  node_services["services<br/>integrations"]
end

subgraph group_grp_ext["Extensibility"]
  node_plugins["plugins<br/>extensibility"]
  node_skills["skills<br/>workflows"]
  node_mcp["MCP<br/>tool protocol"]
end

subgraph group_grp_remote["Remote & bridge"]
  node_bridge["bridge"]
  node_remote["remote"]
  node_server["server<br/>direct connect"]
  node_transports["transports<br/>network io"]
end

subgraph group_grp_data["Persistence & memory"]
  node_history["history<br/>turn log<br/>[history.ts]"]
  node_costtracker["cost tracker<br/>usage accounting<br/>[cost-tracker.ts]"]
  node_memdir["memdir<br/>memory store"]
  node_compact["compact<br/>context reduction"]
end

node_main -->|"starts"| node_entrypoints
node_entrypoints -->|"bootstraps"| node_setup
node_setup -->|"selects mode"| node_screens
node_screens -->|"drives"| node_queryengine
node_queryengine -->|"reads"| node_querymods
node_queryengine -->|"appends"| node_history
node_queryengine -->|"tracks"| node_costtracker
node_queryengine -->|"invokes"| node_toolregistry
node_commands -->|"mutates"| node_appstate
node_commands -->|"calls"| node_services
node_toolregistry -->|"implements"| node_toolimpls
node_toolimpls -->|"checks"| node_permhooks
node_permhooks -->|"prompts"| node_permui
node_permhooks -->|"evaluates"| node_permutils
node_components -->|"renders"| node_appstate
node_components -->|"uses"| node_hooks
node_components -->|"built on"| node_ink
node_services -->|"runs"| node_compact
node_services -->|"persists"| node_memdir
node_services -->|"integrates"| node_mcp
node_plugins -->|"extends"| node_toolregistry
node_plugins -->|"extends"| node_commands
node_skills -->|"guides"| node_toolregistry
node_bridge -->|"auths via"| node_services
node_bridge -->|"connects"| node_remote
node_remote -->|"spawns"| node_server
node_remote -->|"transports"| node_transports
node_queryengine -->|"requests"| node_services
node_queryengine -->|"triggers"| node_compact
node_queryengine -->|"updates"| node_context
node_history -->|"informs"| node_memdir

click node_main "https://github.com/alesha-pro/claude-code/blob/main/src/main.tsx"
click node_entrypoints "https://github.com/alesha-pro/claude-code/tree/main/src/entrypoints"
click node_setup "https://github.com/alesha-pro/claude-code/blob/main/src/setup.ts"
click node_screens "https://github.com/alesha-pro/claude-code/tree/main/src/screens"
click node_queryengine "https://github.com/alesha-pro/claude-code/blob/main/src/QueryEngine.ts"
click node_querymods "https://github.com/alesha-pro/claude-code/tree/main/src/query"
click node_context "https://github.com/alesha-pro/claude-code/blob/main/src/context.ts"
click node_history "https://github.com/alesha-pro/claude-code/blob/main/src/history.ts"
click node_costtracker "https://github.com/alesha-pro/claude-code/blob/main/src/cost-tracker.ts"
click node_appstate "https://github.com/alesha-pro/claude-code/tree/main/src/state"
click node_components "https://github.com/alesha-pro/claude-code/tree/main/src/components"
click node_ink "https://github.com/alesha-pro/claude-code/tree/main/src/ink"
click node_hooks "https://github.com/alesha-pro/claude-code/tree/main/src/hooks"
click node_commands "https://github.com/alesha-pro/claude-code/blob/main/src/commands.ts"
click node_toolregistry "https://github.com/alesha-pro/claude-code/blob/main/src/tools.ts"
click node_toolimpls "https://github.com/alesha-pro/claude-code/tree/main/src/tools"
click node_permhooks "https://github.com/alesha-pro/claude-code/tree/main/src/hooks/toolPermission"
click node_permui "https://github.com/alesha-pro/claude-code/tree/main/src/components/permissions"
click node_permutils "https://github.com/alesha-pro/claude-code/tree/main/src/utils/permissions"
click node_services "https://github.com/alesha-pro/claude-code/tree/main/src/services"
click node_plugins "https://github.com/alesha-pro/claude-code/tree/main/src/plugins"
click node_skills "https://github.com/alesha-pro/claude-code/tree/main/src/skills"
click node_mcp "https://github.com/alesha-pro/claude-code/tree/main/src/services/mcp"
click node_bridge "https://github.com/alesha-pro/claude-code/tree/main/src/bridge"
click node_remote "https://github.com/alesha-pro/claude-code/tree/main/src/remote"
click node_server "https://github.com/alesha-pro/claude-code/tree/main/src/server"
click node_transports "https://github.com/alesha-pro/claude-code/tree/main/src/cli/transports"
click node_memdir "https://github.com/alesha-pro/claude-code/tree/main/src/memdir"
click node_compact "https://github.com/alesha-pro/claude-code/tree/main/src/services/compact"

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_entrypoints,node_setup,node_screens,node_plugins,node_skills,node_mcp toneBlue
class node_queryengine,node_querymods,node_context,node_bridge,node_remote,node_server,node_transports toneAmber
class node_appstate,node_components,node_ink,node_hooks,node_history,node_costtracker,node_memdir,node_compact toneMint
class node_commands,node_toolregistry,node_toolimpls toneRose
class node_permhooks,node_permui,node_permutils toneIndigo
class node_services toneTeal
```

## Components

### Boot & entry

Startup paths, modes, and initialization.

- [main](https://github.com/alesha-pro/claude-code/blob/main/src/main.tsx): entrypoint · Bun/TypeScript CLI bootstrap. · `src/main.tsx`
- [entrypoints](https://github.com/alesha-pro/claude-code/tree/main/src/entrypoints): cli boot · CLI and SDK entrypaths. · `src/entrypoints`
- [setup](https://github.com/alesha-pro/claude-code/blob/main/src/setup.ts): startup init · Preloads settings, auth, and environment state. · `src/setup.ts`
- [screens](https://github.com/alesha-pro/claude-code/tree/main/src/screens): modes · Top-level screens like REPL, doctor, resume. · `src/screens`

### Session core

Conversation orchestration and stateful session data.

- [QueryEngine](https://github.com/alesha-pro/claude-code/blob/main/src/QueryEngine.ts): orchestrator · Streaming model loop, retries, token accounting, tool-call cycles. · `src/QueryEngine.ts`
- [query ctx](https://github.com/alesha-pro/claude-code/tree/main/src/query): prompt state · Prompt context, config, stop hooks, and token budget. · `src/query`
- [context](https://github.com/alesha-pro/claude-code/blob/main/src/context.ts): session context · Shared conversation and runtime context. · `src/context.ts`

### Terminal UI

Ink/React rendering, state, and interaction.

- [App state](https://github.com/alesha-pro/claude-code/tree/main/src/state): session store · Central UI/session state store and selectors. · `src/state`
- [components](https://github.com/alesha-pro/claude-code/tree/main/src/components): ink ui · React/Ink views for prompts, messages, dialogs, and panels. · `src/components`
- [ink](https://github.com/alesha-pro/claude-code/tree/main/src/ink): renderer · Custom Ink renderer and terminal primitives. · `src/ink`
- [hooks](https://github.com/alesha-pro/claude-code/tree/main/src/hooks): react hooks · Interaction, polling, and integration hooks. · `src/hooks`

### Tools & commands

User commands and agent tool execution surface.

- [commands](https://github.com/alesha-pro/claude-code/blob/main/src/commands.ts): slash cmds · Slash command registry and command implementations. · `src/commands.ts`
- [tools](https://github.com/alesha-pro/claude-code/blob/main/src/tools.ts): agent tools · Tool registry and typed action surface. · `src/tools.ts`
- [tool impls](https://github.com/alesha-pro/claude-code/tree/main/src/tools): tool modules · Shell, file, search, MCP, LSP, task, and agent tools. · `src/tools`

### Policy & permissions

Security checks, tool approval, and policy enforcement.

- [permission hooks](https://github.com/alesha-pro/claude-code/tree/main/src/hooks/toolPermission): approval flow · Permission request handling for risky tool calls. · `src/hooks/toolPermission`
- [permission UI](https://github.com/alesha-pro/claude-code/tree/main/src/components/permissions): approval dialogs · Dialogs and prompts for user approvals. · `src/components/permissions`
- [permission utils](https://github.com/alesha-pro/claude-code/tree/main/src/utils/permissions): policy rules · Policy rules, classifiers, and permission mode logic. · `src/utils/permissions`

### Services

External integrations and long-running background services.

- [services](https://github.com/alesha-pro/claude-code/tree/main/src/services): integrations · Cloud API, analytics, telemetry, limits, and background services. · `src/services`

### Extensibility

Plugins, skills, and MCP-based extension points.

- [plugins](https://github.com/alesha-pro/claude-code/tree/main/src/plugins): extensibility · Plugin loading, builtin plugins, and marketplace support. · `src/plugins`
- [skills](https://github.com/alesha-pro/claude-code/tree/main/src/skills): workflows · Bundled and loaded reusable workflows. · `src/skills`
- [MCP](https://github.com/alesha-pro/claude-code/tree/main/src/services/mcp): tool protocol · Model Context Protocol client, auth, and server coordination. · `src/services/mcp`

### Remote & bridge

IDE, remote, server, and transport control planes.

- [bridge](https://github.com/alesha-pro/claude-code/tree/main/src/bridge): ide bridge · IDE-facing bidirectional bridge and session control. · `src/bridge`
- [remote](https://github.com/alesha-pro/claude-code/tree/main/src/remote): remote sessions · Remote session manager and session transports. · `src/remote`
- [server](https://github.com/alesha-pro/claude-code/tree/main/src/server): direct connect · Direct-connect session server and manager. · `src/server`
- [transports](https://github.com/alesha-pro/claude-code/tree/main/src/cli/transports): network io · SSE, WebSocket, and batch transport adapters. · `src/cli/transports`

### Persistence & memory

History, memory, compacting, and persistence layers.

- [history](https://github.com/alesha-pro/claude-code/blob/main/src/history.ts): turn log · Conversation turn history and replay support. · `src/history.ts`
- [cost tracker](https://github.com/alesha-pro/claude-code/blob/main/src/cost-tracker.ts): usage accounting · Tracks token and cost usage. · `src/cost-tracker.ts`
- [memdir](https://github.com/alesha-pro/claude-code/tree/main/src/memdir): memory store · Persistent memory discovery and team memory paths. · `src/memdir`
- [compact](https://github.com/alesha-pro/claude-code/tree/main/src/services/compact): context reduction · Compacting and session-memory reduction pipeline. · `src/services/compact`

## Connections

- main → entrypoints: starts · Main dispatches into CLI entrypoints.
- entrypoints → setup: bootstraps · Startup loads configuration and environment state.
- setup → screens: selects mode · Bootstrap chooses the active screen or workflow.
- screens → QueryEngine: drives · Interactive screens hand off to the conversation engine.
- QueryEngine → query ctx: reads · Engine consumes prompt context and execution config.
- QueryEngine → history: appends · Turns and outcomes are persisted to history.
- QueryEngine → cost tracker: tracks · Token and usage accounting is updated during runs.
- QueryEngine → tools: invokes · Model tool calls are dispatched through the tool layer.
- commands → App state: mutates · Commands update session and UI state.
- commands → services: calls · Commands may trigger service workflows or remote actions.
- tools → tool impls: implements · Registry is backed by concrete tool modules.
- tool impls → permission hooks: checks · Potentially dangerous tools flow through permission hooks.
- permission hooks → permission UI: prompts · Interactive approval dialogs collect user decisions.
- permission hooks → permission utils: evaluates · Policy and classifier rules determine allowed usage.
- components → App state: renders · UI is driven by central state and selectors.
- components → hooks: uses · Components rely on app hooks for behavior and data.
- components → ink: built on · Terminal UI is rendered through Ink primitives.
- services → compact: runs · Background services include compacting and memory reduction.
- services → memdir: persists · Services read/write durable memory artifacts.
- services → MCP: integrates · Services coordinate MCP connections and server auth.
- plugins → tools: extends · Plugins can add tools and commands.
- plugins → commands: extends · Plugins contribute slash commands and UI flows.
- skills → tools: guides · Skills package reusable workflows exposed to the agent.
- bridge → services: auths via · Bridge sessions use service-backed auth and status.
- bridge → remote: connects · Bridge can route into remote session control flows.
- remote → server: spawns · Remote session handling includes direct-connect server paths.
- remote → transports: transports · Remote I/O uses SSE and WebSocket adapters.
- QueryEngine → services: requests · Model inference, telemetry, and limits depend on service clients.
- QueryEngine → compact: triggers · Long conversations can be compacted by the engine.
- QueryEngine → context: updates · Session context is mutated as the conversation evolves.
- history → memdir: informs · Historical turns feed durable memory discovery.
