# prassamin/claude-code architecture

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

## Overview

1. **Product shape**
   - This is a terminal-first agentic CLI for Claude Code, not a generic app server.
   - The runtime is **Bun**, and the primary interactive surface is a **React-based TUI** built on a custom `src/ink` rendering/runtime layer.

2. **Top-level execution path**
   - The main entrypoint is `src/entrypoints/cli.tsx`, with other entrypoints for MCP and SDK integration.
   - Startup wiring goes through `src/main.tsx`, `src/setup.ts`, and app state/bootstrap modules before the UI and agent loop start.

3. **UI and rendering boundary**
   - `src/components`, `src/screens`, `src/commands`, and `src/ink` form the presentation layer.
   - `src/ink` is a substantial internal terminal UI framework: it handles layout, input events, focus, screen rendering, and terminal semantics, while the rest of the React components implement dialogs, panels, menus, and message views.

4. **State and session model**
   - `src/state`, `src/context`, `src/history.ts`, and `src/bootstrap/state.ts` hold the persistent in-memory application state.
   - This state tracks conversation history, active tasks, selected model, permissions, session metadata, queued messages, and UI overlays.

5. **Agent orchestration core**
   - The heart of the system is the query/assistant loop in `src/QueryEngine.ts`, `src/assistant`, `src/tasks`, and `src/tools`.
   - User input is transformed into prompts/commands, routed into the query engine, executed through tools, and then rendered back as messages, task updates, and status indicators.

6. **Tool execution pipeline**
   - `src/tools/*` contains the actual capabilities: bash, file read/write/edit, search, LSP, MCP, agent spawning, web fetch/search, task management, plan/worktree mode, and more.
   - Most tools have three parts: execution logic, prompt/schema metadata, and a TUI-facing `UI.tsx` for permission or progress display.

7. **Permission and safety boundary**
   - Tool use is mediated by `src/hooks/toolPermission`, `src/components/permissions`, and the permission utilities in `src/utils/permissions`.
   - This is a major architectural boundary: tool requests are classified, may be approved/denied/routed to dialogs, and are further constrained by sandbox/read-only/path/danger checks before execution.

8. **External API / cloud dependency layer**
   - `src/services/api`, `src/services/oauth`, `src/services/analytics`, and related service modules encapsulate all external network interactions.
   - These include Anthropic API calls, usage/rate-limit reporting, OAuth flows, analytics/telemetry, prompt caching, and product-level service endpoints.

9. **Remote session and bridge subsystem**
   - `src/bridge`, `src/remote`, `src/server`, and `src/upstreamproxy` implement remote control and session ingress/egress paths.
   - This layer handles WebSocket/SSE-style transport, session resume, remote permissions, REPL/bridge modes, and direct-connect style session management.

10. **MCP and plugin ecosystem**
   - `src/services/mcp`, `src/commands/mcp`, `src/components/mcp`, and `src/plugins` implement Model Context Protocol support and plugin loading/management.
   - The architecture supports both local and remote MCP servers, plugin marketplaces, plugin trust/validation, and runtime discovery of plugin-provided commands, tools, hooks, and output styles.

11. **Background capabilities and “assistant-adjacent” subsystems**
   - `src/services/compact`, `src/services/memory`, `src/services/autoDream`, `src/services/lsp`, `src/services/voice`, and `src/services/tips` are background services that augment the main agent loop.
   - These subsystems handle summarization/compaction, memory extraction and sync, automated dreaming/consolidation, language-server integration, speech/voice, and user guidance/tips.

12. **Task and multi-agent model**
   - `src/tasks`, `src/components/tasks`, `src/tools/AgentTool`, and swarm-related utilities support multiple task types and nested agents.
   - The system distinguishes local shell tasks, local/remote agent tasks, in-process teammates, and background/remote sessions; UI components surface their progress and results in a unified task list.

13. **Configuration, settings, and persistence**
   - `src/utils/settings`, `src/services/settingsSync`, `src/services/remoteManagedSettings`, `src/utils/secureStorage`, and `src/memdir` manage user/org settings and local persisted state.
   - There are clear boundaries between user-editable config, managed/remote config, secure secrets, session storage, memory files, and cached indices.

14. **Platform and environment integration**
   - The repo contains substantial terminal/shell integration (`src/utils/shell`, `src/utils/bash`, `src/utils/powershell`), worktree/git helpers, sandbox/computer-use support, and native shims under `src/native-ts`.
   - This is a local automation product first: it must safely interact with the host shell, filesystem, IDE, and optionally browser/computer-use integrations.

15. **Operational concerns**
   - Telemetry, rate limits, profiling, error logging, and diagnostics are first-class via `src/services/analytics`, `src/utils/telemetry`, `src/utils/diagLogs`, `src/services/rateLimitMessages`, and `src/components/doctor`.
   - The architecture is built to keep the core loop responsive while asynchronous background watchers, network calls, and task updates feed back into the TUI.

16. **Important diagram boundary**
   - The most accurate high-level diagram is: **terminal UI + command layer** feeding a **central stateful agent loop**, which fans out to **tool execution/safety**, **background services**, and **external cloud/remote integrations**, with results flowing back into **message history and task UI**.

Main entry points: [`src/QueryEngine.ts`](https://github.com/prassamin/claude-code/blob/main/src/QueryEngine.ts) (Query engine), [`src/state`](https://github.com/prassamin/claude-code/tree/main/src/state) (State store), [`src/components/App.tsx`](https://github.com/prassamin/claude-code/blob/main/src/components/App.tsx) (App shell), [`src/tools`](https://github.com/prassamin/claude-code/tree/main/src/tools) (Tool hub)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["Entry & runtime"]
  node_entry_cli["CLI entry<br/>entrypoint<br/>[cli.tsx]"]
  node_startup["Bootstrap<br/>startup<br/>[main.tsx]"]
end

subgraph group_group_ui["Terminal UI"]
  node_app_ui["App shell<br/>react-tui<br/>[App.tsx]"]
  node_ink_runtime["Ink core<br/>terminal-ui framework"]
  node_screens["Screens"]
  node_ui_components["Panels<br/>presentation"]
end

subgraph group_group_core["Agent core"]
  node_state_store[("State store<br/>app state")]
  node_history["History<br/>session log<br/>[history.ts]"]
  node_query_engine{{"Query engine<br/>agent loop<br/>[QueryEngine.ts]"}}
  node_assistant_tasks["Assistants<br/>orchestration"]
  node_task_model["Tasks<br/>task model"]
end

subgraph group_group_tools["Tools"]
  node_tool_hub["Tool hub<br/>tooling"]
  node_file_shell_tools["File & shell<br/>tool family"]
  node_agent_mcp_tools["Agent & MCP<br/>tool family"]
end

subgraph group_group_safety["Safety & permissions"]
  node_permission_layer{{"Permissions<br/>safety gate"}}
  node_sandbox_checks["Sandbox checks<br/>policy utils"]
end

subgraph group_group_integrations["Integrations"]
  node_api_services["API services<br/>cloud integrations"]
  node_remote_bridge["Remote bridge<br/>remote control"]
  node_mcp_plugins["MCP & plugins<br/>extension platform"]
  node_background_services["Background svc<br/>background services"]
end

subgraph group_group_platform["Platform"]
  node_platform_env["Platform<br/>local integration"]
end

node_entry_cli -->|"boot"| node_startup
node_startup -->|"mounts"| node_app_ui
node_app_ui -->|"renders via"| node_ink_runtime
node_app_ui -->|"navigates"| node_screens
node_app_ui -->|"composes"| node_ui_components
node_ui_components -->|"reads/writes"| node_state_store
node_screens -->|"binds"| node_state_store
node_state_store -->|"persists"| node_history
node_state_store -->|"drives"| node_query_engine
node_query_engine -->|"orchestrates"| node_assistant_tasks
node_assistant_tasks -->|"spawns"| node_task_model
node_query_engine -->|"invokes"| node_tool_hub
node_tool_hub -->|"includes"| node_file_shell_tools
node_tool_hub -->|"includes"| node_agent_mcp_tools
node_tool_hub -->|"checked by"| node_permission_layer
node_permission_layer -->|"enforces"| node_sandbox_checks
node_file_shell_tools -->|"uses"| node_platform_env
node_agent_mcp_tools -->|"extends"| node_mcp_plugins
node_query_engine -->|"augments"| node_background_services
node_query_engine -->|"calls"| node_api_services
node_query_engine -->|"syncs"| node_remote_bridge
node_api_services -.->|"supports"| node_mcp_plugins
node_remote_bridge -->|"streams"| node_task_model
node_background_services -->|"updates"| node_state_store

click node_entry_cli "https://github.com/prassamin/claude-code/blob/main/src/entrypoints/cli.tsx"
click node_startup "https://github.com/prassamin/claude-code/blob/main/src/main.tsx"
click node_app_ui "https://github.com/prassamin/claude-code/blob/main/src/components/App.tsx"
click node_ink_runtime "https://github.com/prassamin/claude-code/tree/main/src/ink"
click node_screens "https://github.com/prassamin/claude-code/tree/main/src/screens"
click node_ui_components "https://github.com/prassamin/claude-code/tree/main/src/components"
click node_state_store "https://github.com/prassamin/claude-code/tree/main/src/state"
click node_history "https://github.com/prassamin/claude-code/blob/main/src/history.ts"
click node_query_engine "https://github.com/prassamin/claude-code/blob/main/src/QueryEngine.ts"
click node_assistant_tasks "https://github.com/prassamin/claude-code/tree/main/src/assistant"
click node_task_model "https://github.com/prassamin/claude-code/tree/main/src/tasks"
click node_tool_hub "https://github.com/prassamin/claude-code/tree/main/src/tools"
click node_file_shell_tools "https://github.com/prassamin/claude-code/tree/main/src/tools/BashTool"
click node_agent_mcp_tools "https://github.com/prassamin/claude-code/tree/main/src/tools/AgentTool"
click node_permission_layer "https://github.com/prassamin/claude-code/tree/main/src/hooks/toolPermission"
click node_sandbox_checks "https://github.com/prassamin/claude-code/tree/main/src/utils/permissions"
click node_api_services "https://github.com/prassamin/claude-code/tree/main/src/services/api"
click node_remote_bridge "https://github.com/prassamin/claude-code/tree/main/src/bridge"
click node_mcp_plugins "https://github.com/prassamin/claude-code/tree/main/src/services/mcp"
click node_background_services "https://github.com/prassamin/claude-code/tree/main/src/services/compact"
click node_platform_env "https://github.com/prassamin/claude-code/tree/main/src/utils"

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_entry_cli,node_startup,node_platform_env toneBlue
class node_app_ui,node_ink_runtime,node_screens,node_ui_components toneAmber
class node_state_store,node_history,node_query_engine,node_assistant_tasks,node_task_model toneMint
class node_tool_hub,node_file_shell_tools,node_agent_mcp_tools toneRose
class node_permission_layer,node_sandbox_checks toneIndigo
class node_api_services,node_remote_bridge,node_mcp_plugins,node_background_services toneTeal
```

## Components

### Entry & runtime

CLI entrypoints, startup wiring, and runtime bootstrap.

- [CLI entry](https://github.com/prassamin/claude-code/blob/main/src/entrypoints/cli.tsx): entrypoint · Main terminal entrypoint and alternate MCP/SDK launch paths. · `src/entrypoints/cli.tsx`
- [Bootstrap](https://github.com/prassamin/claude-code/blob/main/src/main.tsx): startup · Startup wiring, setup, and app bootstrapping before the UI loop starts. · `src/main.tsx`

### Terminal UI

React TUI layer and the internal Ink rendering/runtime framework.

- [App shell](https://github.com/prassamin/claude-code/blob/main/src/components/App.tsx): react-tui · Top-level React application composition for the terminal UI. · `src/components/App.tsx`
- [Ink core](https://github.com/prassamin/claude-code/tree/main/src/ink): terminal-ui framework · Custom terminal rendering, layout, focus, events, and screen semantics. · `src/ink`
- [Screens](https://github.com/prassamin/claude-code/tree/main/src/screens): ui screens · Dedicated screen-level views such as REPL, doctor, and resume flows. · `src/screens`
- [Panels](https://github.com/prassamin/claude-code/tree/main/src/components): presentation · Dialogs, message views, prompts, task panels, permissions, and other React components. · `src/components`

### Agent core

Stateful conversation loop, sessions, tasks, and tool orchestration.

- [State store](https://github.com/prassamin/claude-code/tree/main/src/state): app state · Central in-memory app state, selectors, and state transitions. · `src/state`
- [History](https://github.com/prassamin/claude-code/blob/main/src/history.ts): session log · Conversation history and session transcript model. · `src/history.ts`
- [Query engine](https://github.com/prassamin/claude-code/blob/main/src/QueryEngine.ts): agent loop · Main assistant/query loop that turns input into model turns and tool actions. · `src/QueryEngine.ts`
- [Assistants](https://github.com/prassamin/claude-code/tree/main/src/assistant): orchestration · Assistant/session orchestration and task lifecycle coordination. · `src/assistant`
- [Tasks](https://github.com/prassamin/claude-code/tree/main/src/tasks): task model · Task definitions, task execution states, and task-specific UI coordination. · `src/tasks`

### Tools

Capability implementations exposed to the agent.

- [Tool hub](https://github.com/prassamin/claude-code/tree/main/src/tools): tooling · Tool registry and shared tool abstractions connecting the agent loop to capabilities. · `src/tools`
- [File & shell](https://github.com/prassamin/claude-code/tree/main/src/tools/BashTool): tool family · Bash, PowerShell, file read/write/edit, search, and LSP-style local code tools. · `src/tools/BashTool`
- [Agent & MCP](https://github.com/prassamin/claude-code/tree/main/src/tools/AgentTool): tool family · Subagent spawning, MCP resources, workflow tools, and plugin-facing capabilities. · `src/tools/AgentTool`

### Safety & permissions

Approval, sandbox, path, and destructive-action boundaries.

- [Permissions](https://github.com/prassamin/claude-code/tree/main/src/hooks/toolPermission): safety gate · Tool classification, user approval, and permission routing. · `src/hooks/toolPermission`
- [Sandbox checks](https://github.com/prassamin/claude-code/tree/main/src/utils/permissions): policy utils · Read-only, path, filesystem, and destructive-command validation utilities. · `src/utils/permissions`

### Integrations

Cloud APIs, MCP, remote bridge, plugins, and background services.

- [API services](https://github.com/prassamin/claude-code/tree/main/src/services/api): cloud integrations · Anthropic API, usage, analytics, OAuth, and product service calls. · `src/services/api`
- [Remote bridge](https://github.com/prassamin/claude-code/tree/main/src/bridge): remote control · Remote session ingress/egress, bridge modes, and session resume plumbing. · `src/bridge`
- [MCP & plugins](https://github.com/prassamin/claude-code/tree/main/src/services/mcp): extension platform · MCP server management, plugin discovery, trust, validation, and runtime loading. · `src/services/mcp`
- [Background svc](https://github.com/prassamin/claude-code/tree/main/src/services/compact): background services · Compaction, memory, auto-dream, LSP, voice, and tip-generation services. · `src/services/compact`

### Platform

Local shell, filesystem, git, native, and environment integration.

- [Platform](https://github.com/prassamin/claude-code/tree/main/src/utils): local integration · Shell, git, worktree, sandbox, native shims, and host-environment integration. · `src/utils`

## Connections

- CLI entry → Bootstrap: boot · Launches startup wiring and application setup.
- Bootstrap → App shell: mounts · Creates the top-level app shell after initialization.
- App shell → Ink core: renders via · The app is rendered through the custom terminal runtime.
- App shell → Screens: navigates · Routes to dedicated screens and modal flows.
- App shell → Panels: composes · Builds the interactive presentation layer from reusable components.
- Panels → State store: reads/writes · UI reacts to and mutates application state.
- Screens → State store: binds · Screen flows operate on the same session state.
- State store → History: persists · Conversation turns and session metadata are tracked in history.
- State store → Query engine: drives · State changes trigger the main assistant loop.
- Query engine → Assistants: orchestrates · The engine delegates session and assistant lifecycle work.
- Assistants → Tasks: spawns · Assistant work is represented as tasks.
- Query engine → Tool hub: invokes · Model turns request tools through the shared tool layer.
- Tool hub → File & shell: includes · Local file, shell, and code-analysis tools.
- Tool hub → Agent & MCP: includes · Agent spawning, workflow, and MCP-facing tools.
- Tool hub → Permissions: checked by · Tool requests pass through permission mediation.
- Permissions → Sandbox checks: enforces · Permission decisions are constrained by sandbox and safety policy.
- File & shell → Platform: uses · Executes through host shell, filesystem, git, and native helpers.
- Agent & MCP → MCP & plugins: extends · Can surface plugin and MCP-provided functionality.
- Query engine → Background svc: augments · Summarization, memory, LSP, voice, and tips feed the loop.
- Query engine → API services: calls · Model and product requests go through external service clients.
- Query engine → Remote bridge: syncs · Remote sessions and bridge ingress/egress connect to the loop.
- API services → MCP & plugins: supports · Cloud-backed service access and remote MCP management coexist.
- Remote bridge → Tasks: streams · Remote activity is surfaced as tasks and session progress.
- Background svc → State store: updates · Background work feeds state, overlays, and status indicators.
