# yasasbanukaofficial/claude-code architecture

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

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

## Overview

1. **What this repo is**
   - This is a large **TypeScript/React-based terminal application** built around an AI coding agent. The runtime is centered on **Bun/Node**, with **Ink** providing the terminal UI layer and a command-driven CLI surface.

2. **Primary entrypoints and boot path**
   - `src/main.tsx`, `src/entrypoints/cli.tsx`, `src/setup.ts`, and `src/bootstrap/*` form the startup path.
   - These files likely initialize configuration, load plugins/skills, restore session state, set up auth/settings, and then mount the main app in the terminal renderer.

3. **UI shell vs. agent core**
   - `src/components/*`, `src/screens/*`, `src/ink/*`, and `src/keybindings/*` are the presentation layer.
   - `src/state/*`, `src/context/*`, and many hooks under `src/hooks/*` hold the interactive state machine, global context, command queue, notifications, and keyboard/input handling.
   - The UI is not a typical web app; it is a **terminal-first React app** with custom layout/rendering primitives.

4. **Core conversation and execution loop**
   - `src/QueryEngine.ts`, `src/assistant/*`, `src/history.ts`, `src/tasks.ts`, `src/utils/processUserInput/*`, and `src/utils/messages/*` appear to drive the agent loop:
     user input -> classify/parse -> build prompt/context -> send to model -> receive assistant/tool events -> render messages and update history.
   - This is the central data flow of the app and the main boundary between UI state and model/tool execution.

5. **Tool system**
   - `src/tools/*`, `src/Tool.ts`, and `src/constants/tools.ts` define the tool catalog and tool contract.
   - Tools cover file operations, shell execution, web search/fetch, LSP, MCP resources, task/subagent management, planning, memory, and remote triggers.
   - `src/services/tools/*` handles orchestration and streaming execution, so tool calls are executed incrementally and feed progress/results back into the UI.

6. **Permissions and safety boundary**
   - `src/components/permissions/*`, `src/hooks/toolPermission/*`, `src/utils/permissions/*`, `src/services/policyLimits/*`, and the Bash/PowerShell validation utilities enforce what the agent can do.
   - This boundary is important: tool execution is gated by permission prompts, rule matching, sandbox checks, destructive-command detection, filesystem/path validation, and mode-dependent policies.

7. **Remote control and bridge layer**
   - `src/bridge/*`, `src/remote/*`, `src/server/*`, and `src/commands/bridge*` implement IDE/remote-session integration and bridge transport.
   - This layer appears to connect the local terminal app to external controllers, sessions, or background workers through WebSocket/SSE/REPL-style transports and session runners.
   - It likely carries inbound messages, attachments, permissions callbacks, and session state across process or device boundaries.

8. **Multi-agent and task orchestration**
   - `src/coordinator/*`, `src/tasks/*`, `src/tools/AgentTool/*`, `src/utils/swarm/*`, and `src/components/tasks/*` model autonomous sub-agents and background work.
   - There are distinct task types for local shell, local agent, remote agent, dream/background work, and in-process teammates.
   - The architecture suggests a **hierarchical agent system**: the main session can spawn specialized agents, track their progress, and merge their outputs back into the parent conversation.

9. **External integrations**
   - **MCP**: `src/services/mcp/*`, `src/commands/mcp/*`, `src/components/mcp/*`, and MCP-related tools expose Model Context Protocol servers/clients and resource approval flows.
   - **Plugins/skills**: `src/services/plugins/*`, `src/utils/plugins/*`, `src/skills/*`, and `src/components/plugin/*` provide extensibility and marketplace-style discovery/installation.
   - **Auth/OAuth and analytics**: `src/services/oauth/*`, `src/services/api/*`, and `src/services/analytics/*` show cloud-backed authentication, usage reporting, and telemetry.
   - **LSP and editor integration**: `src/services/lsp/*`, `src/tools/LSPTool/*`, and `src/components/ide/*` support code intelligence and IDE connection.

10. **Memory, compaction, and background maintenance**
   - `src/services/compact/*`, `src/services/SessionMemory/*`, `src/services/autoDream/*`, `src/memdir/*`, and `src/utils/memory/*` manage durable memory and context reduction.
   - These services read/write memory files, summarize sessions, compact long conversations, and periodically consolidate signal into smaller durable state.
   - This is a key architecture boundary: long-lived session knowledge is separated from transient chat context.

11. **Model/prompt/configuration layer**
   - `src/constants/*`, `src/utils/model/*`, `src/utils/systemPrompt*`, `src/services/claudeAiLimits.ts`, `src/services/tokenEstimation.ts`, and `src/utils/config*` shape how prompts are built and which models/capabilities are available.
   - This layer controls model selection, token budget, prompting policy, and feature gating across the app.

12. **Persistence and state stores**
   - `src/utils/sessionStorage*`, `src/utils/settings/*`, `src/utils/filePersistence/*`, `src/utils/cachePaths.ts`, `src/utils/secureStorage/*`, and `src/state/AppStateStore.ts` indicate a mix of local durable storage and in-memory app state.
   - The app persists settings, auth, session history, caches, plugin state, and some secure credentials locally, while the live session state remains in the React/store layer.

13. **Command surface**
   - `src/commands/*` is a large command registry for the CLI, covering session management, login/logout, config, plugins, bridge, resume, status, review, sandbox, export, and many specialized workflows.
   - These commands are the user-facing control plane around the core assistant runtime.

14. **Overall architectural shape**
   - The repo is best understood as a **terminal-hosted agent platform** with four major planes:
     1. **Interactive UI/runtime** in Ink/React
     2. **Agent execution engine** for prompts, tools, and tasks
     3. **Integration plane** for IDE, MCP, plugins, remote sessions, auth, and telemetry
     4. **Safety/persistence plane** for permissions, sandboxing, memory, settings, and session storage
   - For a diagram, the main arrows run from **user input and external events** into the UI/state layer, then into the **query/tool orchestration layer**, and back out through **messages, task updates, and remote/bridge transports**.

Main entry points: [`src/services/tools/toolOrchestration.ts`](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/tools/toolOrchestration.ts) (Tool Exec), [`src/QueryEngine.ts`](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/QueryEngine.ts) (Query Loop), [`src/components/App.tsx`](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/components/App.tsx) (App Shell), [`src/state/AppStateStore.ts`](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/state/AppStateStore.ts) (App State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_runtime["Runtime"]
  node_n_main["Startup<br/>entrypoints<br/>[main.tsx]"]
  node_n_cli["CLI<br/>entrypoints<br/>[cli.tsx]"]
  node_n_ink["Ink Core<br/>terminal renderer<br/>[ink.tsx]"]
end

subgraph group_g_ui["UI Shell"]
  node_n_appui["App Shell<br/>terminal UI<br/>[App.tsx]"]
  node_n_state[("App State<br/>react store<br/>[AppStateStore.ts]")]
  node_n_input["Input Flow<br/>input processing<br/>[useCommandQueue.ts]"]
end

subgraph group_g_engine["Agent Engine"]
  node_n_query{{"Query Loop<br/>agent loop<br/>[QueryEngine.ts]"}}
  node_n_history["History<br/>conversation memory<br/>[history.ts]"]
  node_n_tasks["Task System<br/>execution orchestration<br/>[tasks.ts]"]
end

subgraph group_g_tools["Tools"]
  node_n_tools["Tool Catalog<br/>tool definitions<br/>[Tool.ts]"]
  node_n_toolexec{{"Tool Exec<br/>tool orchestration"}}
  node_n_bash["Shell Tools<br/>shell/file tools<br/>[BashTool.tsx]"]
  node_n_agenttool["Agent Tools<br/>[AgentTool.tsx]"]
end

subgraph group_g_integrations["Integrations"]
  node_n_bridge{{"Bridge<br/>remote control<br/>[bridgeMain.ts]"}}
  node_n_remote["Remote Sessions<br/>remote runtime"]
  node_n_mcp["MCP<br/>protocol integration"]
  node_n_plugins["Plugins<br/>extensibility"]
  node_n_lsp["LSP<br/>code intelligence"]
  node_n_auth["Auth & Telemetry<br/>cloud services<br/>[client.ts]"]
end

subgraph group_g_state["State & Safety"]
  node_n_safety["Permissions<br/>safety boundary<br/>[permissions.ts]"]
  node_n_memory[("Memory<br/>durable context<br/>[sessionMemory.ts]")]
  node_n_persist[("Persistence<br/>local storage<br/>[sessionStorage.ts]")]
  node_n_prompts["Prompts<br/>model policy<br/>[systemPrompt.ts]"]
end

node_n_main -->|"boot"| node_n_cli
node_n_main -->|"mount"| node_n_ink
node_n_cli -->|"launch"| node_n_appui
node_n_ink -->|"render"| node_n_appui
node_n_appui -->|"read/write"| node_n_state
node_n_input -->|"submit"| node_n_query
node_n_state -->|"drive"| node_n_input
node_n_query -->|"build prompt"| node_n_prompts
node_n_query -->|"append"| node_n_history
node_n_query -->|"invoke tools"| node_n_toolexec
node_n_toolexec -->|"resolve"| node_n_tools
node_n_toolexec -->|"run"| node_n_bash
node_n_toolexec -->|"spawn"| node_n_agenttool
node_n_toolexec -->|"track"| node_n_tasks
node_n_tasks -->|"report"| node_n_appui
node_n_bridge -->|"connect"| node_n_remote
node_n_bridge -->|"events"| node_n_appui
node_n_remote -->|"host"| node_n_tasks
node_n_mcp -->|"serve tools"| node_n_toolexec
node_n_plugins -->|"extend"| node_n_tools
node_n_plugins -->|"augment UI"| node_n_appui
node_n_lsp -->|"support"| node_n_bash
node_n_auth -->|"store creds"| node_n_persist
node_n_safety -->|"gate"| node_n_toolexec
node_n_memory -->|"context"| node_n_query
node_n_persist -->|"restore"| node_n_state
node_n_prompts -->|"shape"| node_n_query

click node_n_main "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/main.tsx"
click node_n_cli "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/entrypoints/cli.tsx"
click node_n_ink "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/ink/ink.tsx"
click node_n_appui "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/components/App.tsx"
click node_n_state "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/state/AppStateStore.ts"
click node_n_input "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/hooks/useCommandQueue.ts"
click node_n_query "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/QueryEngine.ts"
click node_n_history "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/history.ts"
click node_n_tasks "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/tasks.ts"
click node_n_tools "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/Tool.ts"
click node_n_toolexec "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/tools/toolOrchestration.ts"
click node_n_bash "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/tools/BashTool/BashTool.tsx"
click node_n_agenttool "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/tools/AgentTool/AgentTool.tsx"
click node_n_bridge "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/bridge/bridgeMain.ts"
click node_n_remote "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/remote/RemoteSessionManager.ts"
click node_n_mcp "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_n_plugins "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts"
click node_n_lsp "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/lsp/LSPServerManager.ts"
click node_n_auth "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/oauth/client.ts"
click node_n_safety "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/utils/permissions/permissions.ts"
click node_n_memory "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/SessionMemory/sessionMemory.ts"
click node_n_persist "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/utils/sessionStorage.ts"
click node_n_prompts "https://github.com/yasasbanukaofficial/claude-code/blob/main/src/utils/systemPrompt.ts"

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_n_main,node_n_cli,node_n_ink toneBlue
class node_n_appui,node_n_state,node_n_input toneAmber
class node_n_query,node_n_history,node_n_tasks toneMint
class node_n_tools,node_n_toolexec,node_n_bash,node_n_agenttool toneRose
class node_n_bridge,node_n_remote,node_n_mcp,node_n_plugins,node_n_lsp,node_n_auth toneIndigo
class node_n_safety,node_n_memory,node_n_persist,node_n_prompts toneTeal
```

## Components

### Runtime

Startup, CLI surface, and terminal renderer

- [Startup](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/main.tsx): entrypoints · CLI and app bootstrap path · `src/main.tsx`
- [CLI](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/entrypoints/cli.tsx): entrypoints · Command entrypoint and handlers · `src/entrypoints/cli.tsx`
- [Ink Core](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/ink/ink.tsx): terminal renderer · Custom terminal React renderer and primitives · `src/ink/ink.tsx`

### UI Shell

Ink/React presentation and interaction state

- [App Shell](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/components/App.tsx): terminal UI · Main app screen, prompt, messages, dialogs · `src/components/App.tsx`
- [App State](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/state/AppStateStore.ts): react store · Global session and UI state store · `src/state/AppStateStore.ts`
- [Input Flow](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/hooks/useCommandQueue.ts): input processing · User input, keybindings, and queued commands · `src/hooks/useCommandQueue.ts`

### Agent Engine

Conversation loop, prompts, history, and task execution

- [Query Loop](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/QueryEngine.ts): agent loop · Builds prompts, sends requests, and applies model responses · `src/QueryEngine.ts`
- [History](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/history.ts): conversation memory · Transcript and session history management · `src/history.ts`
- [Task System](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/tasks.ts): execution orchestration · Session, shell, agent, and remote task tracking · `src/tasks.ts`

### Tools

Tool catalog and execution/orchestration

- [Tool Catalog](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/Tool.ts): tool definitions · Tool contracts and available capabilities · `src/Tool.ts`
- [Tool Exec](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/tools/toolOrchestration.ts): tool orchestration · Streaming tool execution and lifecycle coordination · `src/services/tools/toolOrchestration.ts`
- [Shell Tools](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/tools/BashTool/BashTool.tsx): shell/file tools · Bash, PowerShell, file, search, and edit tools · `src/tools/BashTool/BashTool.tsx`
- [Agent Tools](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/tools/AgentTool/AgentTool.tsx): multi-agent tools · Subagent spawning, planning, and task delegation tools · `src/tools/AgentTool/AgentTool.tsx`

### Integrations

Remote control, MCP, plugins, LSP, auth, and telemetry

- [Bridge](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/bridge/bridgeMain.ts): remote control · Local/remote bridge transport and session runner · `src/bridge/bridgeMain.ts`
- [Remote Sessions](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/remote/RemoteSessionManager.ts): remote runtime · Remote session manager and session transport · `src/remote/RemoteSessionManager.ts`
- [MCP](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/mcp/MCPConnectionManager.tsx): protocol integration · Model Context Protocol clients, servers, and approval flows · `src/services/mcp/MCPConnectionManager.tsx`
- [Plugins](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts): extensibility · Plugin discovery, loading, installation, and policy · `src/services/plugins/PluginInstallationManager.ts`
- [LSP](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/lsp/LSPServerManager.ts): code intelligence · Language server integration and diagnostics · `src/services/lsp/LSPServerManager.ts`
- [Auth & Telemetry](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/oauth/client.ts): cloud services · OAuth, API client, analytics, and usage reporting · `src/services/oauth/client.ts`

### State & Safety

Persistence, permissions, memory, settings, and policy

- [Permissions](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/utils/permissions/permissions.ts): safety boundary · Permission prompts, rule matching, sandbox, and policy limits · `src/utils/permissions/permissions.ts`
- [Memory](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/services/SessionMemory/sessionMemory.ts): durable context · Session memory, compaction, and memory files · `src/services/SessionMemory/sessionMemory.ts`
- [Persistence](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/utils/sessionStorage.ts): local storage · Settings, session storage, secure storage, and caches · `src/utils/sessionStorage.ts`
- [Prompts](https://github.com/yasasbanukaofficial/claude-code/blob/main/src/utils/systemPrompt.ts): model policy · System prompts, model config, and token budgeting · `src/utils/systemPrompt.ts`

## Connections

- Startup → CLI: boot · CLI startup enters the command surface
- Startup → Ink Core: mount · Bootstraps the terminal renderer
- CLI → App Shell: launch · Commands can open the interactive terminal app
- Ink Core → App Shell: render · Ink hosts the React terminal UI
- App Shell → App State: read/write · UI consumes and updates shared app state
- Input Flow → Query Loop: submit · User input is normalized into agent requests
- App State → Input Flow: drive · State powers prompt input, shortcuts, and queued actions
- Query Loop → Prompts: build prompt · Query engine assembles context and policy for the model
- Query Loop → History: append · Model turns and events are recorded in history
- Query Loop → Tool Exec: invoke tools · Assistant tool calls are executed through the tool runner
- Tool Exec → Tool Catalog: resolve · Tool runner dispatches by tool contract
- Tool Exec → Shell Tools: run · File, shell, and search operations execute here
- Tool Exec → Agent Tools: spawn · Delegates work to subagents and task tools
- Tool Exec → Task System: track · Tool activity feeds task progress and completion
- Task System → App Shell: report · Task state is surfaced back into the UI
- Bridge → Remote Sessions: connect · Bridge transport carries remote session traffic
- Bridge → App Shell: events · Inbound bridge messages affect local UI and permissions
- Remote Sessions → Task System: host · Remote sessions appear as tracked tasks
- MCP → Tool Exec: serve tools · MCP resources and approvals feed the tool layer
- Plugins → Tool Catalog: extend · Plugins add commands, tools, hooks, and styles
- Plugins → App Shell: augment UI · Plugin state and discovery affect the terminal interface
- LSP → Shell Tools: support · Code intelligence complements file and edit workflows
- Auth & Telemetry → Persistence: store creds · Authentication state is persisted locally
- Permissions → Tool Exec: gate · Permissions and sandbox policy approve or deny actions
- Memory → Query Loop: context · Long-lived memory is injected into the agent loop
- Persistence → App State: restore · Settings and session data hydrate runtime state
- Prompts → Query Loop: shape · Prompt and model policy constrain generation
