# abhirupkumar/claude-code architecture

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

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

## Overview

1. **Overall shape**
   - This repo is a monorepo for a Bun/TypeScript AI agent system with three main surfaces:
     - the **CLI product** under `src/`
     - a separate **web app** under `web/`
     - a standalone **MCP source-explorer server** under `mcp-server/`
   - The core architecture is the CLI agent loop; the web app and MCP server are adjacent interfaces, not the primary runtime.

2. **Primary runtime: CLI + Ink UI**
   - The CLI entrypoints in `src/main.tsx` and `src/entrypoints/cli.tsx` bootstrap configuration, auth, and feature flags, then render a React + Ink terminal UI.
   - `src/components/` contains the terminal screens, dialogs, and message views; `src/screens/` holds full-screen flows like REPL, Doctor, and resume views.
   - `src/state/`, `src/context/`, and many `src/hooks/` files coordinate UI state, session state, keyboard handling, notifications, and live updates.

3. **Core agent loop**
   - The heart of the system is `src/QueryEngine.ts`, which drives LLM calls, streaming responses, reasoning/tool-use loops, retries, token accounting, and context management.
   - User input is normalized through `src/utils/processUserInput/` and command handling, then handed into the query pipeline.
   - The query layer owns the transition from prompt → model response → tool requests → tool results → next turn.

4. **Tool system boundary**
   - Tools live in `src/tools/` and are the main capability boundary of the agent.
   - Each tool is a separate module with its own schema, UI, prompt text, and validation logic.
   - Major tool groups include file operations, shell execution, search, web access, sub-agents, MCP access, tasks, scheduling, and mode/state changes.
   - Tool execution is orchestrated through `src/services/tools/`, especially the streaming executor and orchestration helpers.

5. **Permission and safety layer**
   - Tool use is gated by `src/hooks/toolPermission/` and `src/utils/permissions/`, which determine whether a tool call is allowed, denied, or needs user approval.
   - The UI for these decisions lives in `src/components/permissions/`.
   - This is a major architectural boundary: model intent does not directly equal execution; every sensitive action passes through policy, sandbox, and user confirmation checks.

6. **Command system**
   - Slash commands are registered in `src/commands.ts` and implemented in `src/commands/`.
   - Commands cover session control, review, memory, config, MCP management, compacting, resuming, desktop/mobile handoff, and diagnostics.
   - Conceptually, commands are user-driven control-plane actions, while tools are model-driven action-plane operations.

7. **Service layer for external systems**
   - `src/services/` contains the integration layer that supports the agent loop:
     - `api/` for Anthropic API calls, file/bootstrap flows, and usage/error handling
     - `oauth/` for authentication
     - `mcp/` for Model Context Protocol connectivity
     - `lsp/` for language-server-backed code intelligence
     - `analytics/` and telemetry for usage and feature experimentation
     - `plugins/`, `compact/`, `extractMemories/`, `teamMemorySync/`, and `remoteManagedSettings/` for higher-level platform behaviors
   - These services are mostly infrastructure behind the agent, not user-facing UI.

8. **Bridge and IDE integration**
   - `src/bridge/` is the bidirectional bridge between the CLI and IDE extensions such as VS Code or JetBrains.
   - It handles session lifecycle, messaging, permissions callbacks, JWT/auth utilities, and transport/session management.
   - The bridge is a separate communication plane that lets the CLI and editor synchronize prompts, permissions, and task/session state.

9. **Remote and server modes**
   - `src/server/web/` implements a browser-accessible terminal/session server with auth, pty handling, session management, user storage, and static frontend assets.
   - `src/remote/` adds remote session coordination and websocket-based session transport.
   - These are distinct from the local CLI: they expose the same underlying session/agent model over networked interfaces.

10. **State, persistence, and memory**
   - Persistent user/session memory is handled by `src/memdir/`, `src/history.ts`, `src/assistant/`, and parts of `src/services/SessionMemory/`.
   - `src/tasks/` and `src/services/task...` logic manage long-running work, background tasks, and task output.
   - This layer is where the system preserves continuity across turns, sessions, and remote handoffs.

11. **Extensibility model: plugins, skills, MCP, LSP**
   - `src/plugins/` and `src/utils/plugins/` form the plugin architecture, including discovery, loading, validation, policy, and marketplace support.
   - `src/skills/` is the reusable workflow layer; skills are loaded and invoked as higher-level behaviors.
   - MCP, LSP, and plugins are separate extension channels: MCP connects to external tools/services, LSP to language tooling, and plugins to packaged product extensions.

12. **Web app as a separate product surface**
   - The `web/` directory is a distinct Next.js application with its own API routes, React UI, collaboration features, file viewer, export flows, and settings screens.
   - It shares concepts with the CLI—conversations, tools, permissions, sessions—but is architecturally separate and browser-native.
   - The `web/lib/` layer provides client APIs, collaboration sockets, persistence helpers, search, export formats, and performance tooling.

13. **Build-time and runtime boundaries**
   - The repo uses Bun heavily, and `bun:bundle` feature flags are used to dead-strip code paths for build variants.
   - Scripts in `scripts/` handle bundling, packaging, testing, and CI build orchestration.
   - `mcp-server/` is its own Node/TypeScript package, separate from the main Bun runtime, meant specifically for source exploration through MCP clients.

14. **How to diagram the data flow**
   - The main flow is: **user input in Ink UI → command/input processing → query engine → permission check → tool execution or model response → state/UI update**.
   - Side flows include:
     - **CLI ↔ bridge ↔ IDE**
     - **CLI ↔ remote/server session infrastructure**
     - **CLI ↔ external services** such as Anthropic API, OAuth, MCP, LSP, analytics, and plugins
   - The key architectural boundary is that the model does not act directly; it proposes actions, and the tool/permission/service layers mediate execution.

Main entry points: [`src/QueryEngine.ts`](https://github.com/abhirupkumar/claude-code/blob/main/src/QueryEngine.ts) (Query engine), [`src/services/api/claude.ts`](https://github.com/abhirupkumar/claude-code/blob/main/src/services/api/claude.ts) (Services), [`src/components/App.tsx`](https://github.com/abhirupkumar/claude-code/blob/main/src/components/App.tsx) (Ink UI), [`src/utils/processUserInput/processUserInput.ts`](https://github.com/abhirupkumar/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts) (Input routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_main_entry["CLI entry<br/>bootstrap<br/>[main.tsx]"]
  node_ink_ui["Ink UI<br/>terminal-ui<br/>[App.tsx]"]
  node_state_mgr["App state<br/>ui-state<br/>[AppState.tsx]"]
  node_input_router["Input routing<br/>input-control"]
  node_query_engine["Query engine<br/>agent-loop<br/>[QueryEngine.ts]"]
  node_permission_gate["Permission gate<br/>policy<br/>[permissions.ts]"]
  node_tool_executor["Tool exec<br/>tool-runtime"]
  node_tool_catalog["Tools<br/>capability-layer<br/>[tools.ts]"]
  node_command_system["Commands<br/>control-plane<br/>[commands.ts]"]
  node_services_layer["Services<br/>integration-layer<br/>[claude.ts]"]
  node_bridge["IDE bridge<br/>sync-plane<br/>[bridgeMain.ts]"]
  node_remote_runtime["Remote sessions<br/>network-runtime<br/>[session-manager.ts]"]
  node_memory_tasks["Memory & tasks<br/>persistence<br/>[history.ts]"]
  node_extensions["Extensions<br/>extensibility<br/>[builtinPlugins.ts]"]
end

subgraph group_web["Web app"]
  node_web_app["Web app shell<br/>nextjs-app<br/>[page.tsx]"]
  node_web_runtime["Web runtime<br/>web-ui<br/>[ChatLayout.tsx]"]
  node_web_api["Web API<br/>server-routes<br/>[route.ts]"]
  node_web_lib["Web lib<br/>client-infra<br/>[client.ts]"]
end

subgraph group_mcp["MCP server"]
  node_mcp_server["MCP server<br/>node-service<br/>[index.ts]"]
  node_mcp_http["MCP HTTP<br/>transport<br/>[http.ts]"]
end

node_main_entry -->|"launches"| node_ink_ui
node_ink_ui -->|"reads/writes"| node_state_mgr
node_ink_ui -->|"captures input"| node_input_router
node_input_router -->|"slash commands"| node_command_system
node_input_router -->|"prompt text"| node_query_engine
node_query_engine -->|"checks"| node_permission_gate
node_permission_gate -->|"allows"| node_tool_executor
node_query_engine -->|"requests"| node_tool_executor
node_tool_executor -->|"invokes"| node_tool_catalog
node_query_engine -->|"updates"| node_state_mgr
node_command_system -->|"uses"| node_services_layer
node_query_engine -->|"depends on"| node_services_layer
node_services_layer -->|"persists"| node_memory_tasks
node_bridge -->|"syncs"| node_services_layer
node_bridge -->|"coordinates"| node_ink_ui
node_remote_runtime -->|"hosts"| node_state_mgr
node_remote_runtime -->|"feeds"| node_query_engine
node_extensions -->|"extends"| node_tool_catalog
node_extensions -->|"integrates"| node_services_layer
node_web_app -->|"renders"| node_web_runtime
node_web_app -->|"serves"| node_web_api
node_web_runtime -->|"uses"| node_web_lib
node_web_api -->|"delegates"| node_web_lib
node_mcp_server -->|"hosts"| node_mcp_http
node_mcp_server -.->|"adjacent to"| node_services_layer

click node_main_entry "https://github.com/abhirupkumar/claude-code/blob/main/src/main.tsx"
click node_ink_ui "https://github.com/abhirupkumar/claude-code/blob/main/src/components/App.tsx"
click node_state_mgr "https://github.com/abhirupkumar/claude-code/blob/main/src/state/AppState.tsx"
click node_input_router "https://github.com/abhirupkumar/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts"
click node_query_engine "https://github.com/abhirupkumar/claude-code/blob/main/src/QueryEngine.ts"
click node_permission_gate "https://github.com/abhirupkumar/claude-code/blob/main/src/utils/permissions/permissions.ts"
click node_tool_executor "https://github.com/abhirupkumar/claude-code/blob/main/src/services/tools/StreamingToolExecutor.ts"
click node_tool_catalog "https://github.com/abhirupkumar/claude-code/blob/main/src/tools.ts"
click node_command_system "https://github.com/abhirupkumar/claude-code/blob/main/src/commands.ts"
click node_services_layer "https://github.com/abhirupkumar/claude-code/blob/main/src/services/api/claude.ts"
click node_bridge "https://github.com/abhirupkumar/claude-code/blob/main/src/bridge/bridgeMain.ts"
click node_remote_runtime "https://github.com/abhirupkumar/claude-code/blob/main/src/server/web/session-manager.ts"
click node_memory_tasks "https://github.com/abhirupkumar/claude-code/blob/main/src/history.ts"
click node_extensions "https://github.com/abhirupkumar/claude-code/blob/main/src/plugins/builtinPlugins.ts"
click node_web_app "https://github.com/abhirupkumar/claude-code/blob/main/web/app/page.tsx"
click node_web_runtime "https://github.com/abhirupkumar/claude-code/blob/main/web/components/chat/ChatLayout.tsx"
click node_web_api "https://github.com/abhirupkumar/claude-code/blob/main/web/app/api/chat/route.ts"
click node_web_lib "https://github.com/abhirupkumar/claude-code/blob/main/web/lib/api/client.ts"
click node_mcp_server "https://github.com/abhirupkumar/claude-code/blob/main/mcp-server/src/index.ts"
click node_mcp_http "https://github.com/abhirupkumar/claude-code/blob/main/mcp-server/src/http.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_main_entry,node_ink_ui,node_state_mgr,node_input_router,node_query_engine,node_permission_gate,node_tool_executor,node_tool_catalog,node_command_system,node_services_layer,node_bridge,node_remote_runtime,node_memory_tasks,node_extensions toneBlue
class node_web_app,node_web_runtime,node_web_api,node_web_lib toneAmber
class node_mcp_server,node_mcp_http toneMint
```

## Components

### CLI runtime

Primary Bun/TypeScript agent loop and terminal UI.

- [CLI entry](https://github.com/abhirupkumar/claude-code/blob/main/src/main.tsx): bootstrap · Bootstraps config, auth, flags, and launches the terminal app. · `src/main.tsx`
- [Ink UI](https://github.com/abhirupkumar/claude-code/blob/main/src/components/App.tsx): terminal-ui · React + Ink screens, dialogs, message rendering, and input handling. · `src/components/App.tsx`
- [App state](https://github.com/abhirupkumar/claude-code/blob/main/src/state/AppState.tsx): ui-state · Session, notification, modal, and cross-screen state coordination. · `src/state/AppState.tsx`
- [Input routing](https://github.com/abhirupkumar/claude-code/blob/main/src/utils/processUserInput/processUserInput.ts): input-control · Normalizes user input and routes slash commands versus prompt text. · `src/utils/processUserInput/processUserInput.ts`
- [Query engine](https://github.com/abhirupkumar/claude-code/blob/main/src/QueryEngine.ts): agent-loop · Drives model turns, streaming, retries, token accounting, and tool-use cycles. · `src/QueryEngine.ts`
- [Permission gate](https://github.com/abhirupkumar/claude-code/blob/main/src/utils/permissions/permissions.ts): policy · Decides whether tool calls are allowed, denied, or require approval. · `src/utils/permissions/permissions.ts`
- [Tool exec](https://github.com/abhirupkumar/claude-code/blob/main/src/services/tools/StreamingToolExecutor.ts): tool-runtime · Streams and orchestrates tool execution and tool-result handling. · `src/services/tools/StreamingToolExecutor.ts`
- [Tools](https://github.com/abhirupkumar/claude-code/blob/main/src/tools.ts): capability-layer · Model-facing tool modules for file, shell, search, web, MCP, tasks, and agent actions. · `src/tools.ts`
- [Commands](https://github.com/abhirupkumar/claude-code/blob/main/src/commands.ts): control-plane · Slash command registry and implementations for session and product control. · `src/commands.ts`
- [Services](https://github.com/abhirupkumar/claude-code/blob/main/src/services/api/claude.ts): integration-layer · Shared integrations for API, auth, MCP, LSP, analytics, plugins, compacting, and memory. · `src/services/api/claude.ts`
- [IDE bridge](https://github.com/abhirupkumar/claude-code/blob/main/src/bridge/bridgeMain.ts): sync-plane · Bidirectional bridge for editor integrations, permissions callbacks, and session messaging. · `src/bridge/bridgeMain.ts`
- [Remote sessions](https://github.com/abhirupkumar/claude-code/blob/main/src/server/web/session-manager.ts): network-runtime · Websocket and server-side session infrastructure for remote or browser access. · `src/server/web/session-manager.ts`
- [Memory & tasks](https://github.com/abhirupkumar/claude-code/blob/main/src/history.ts): persistence · Session history, memories, background tasks, and long-running work continuity. · `src/history.ts`
- [Extensions](https://github.com/abhirupkumar/claude-code/blob/main/src/plugins/builtinPlugins.ts): extensibility · Plugin and skill loading plus packaged extension behaviors. · `src/plugins/builtinPlugins.ts`

### Web app

Browser-native conversation and collaboration surface.

- [Web app shell](https://github.com/abhirupkumar/claude-code/blob/main/web/app/page.tsx): nextjs-app · Next.js browser surface for chat, files, sharing, export, and settings. · `web/app/page.tsx`
- [Web runtime](https://github.com/abhirupkumar/claude-code/blob/main/web/components/chat/ChatLayout.tsx): web-ui · Chat layout, command palette, file viewer, collaboration, and notification components. · `web/components/chat/ChatLayout.tsx`
- [Web API](https://github.com/abhirupkumar/claude-code/blob/main/web/app/api/chat/route.ts): server-routes · HTTP routes for chat, files, export, and sharing. · `web/app/api/chat/route.ts`
- [Web lib](https://github.com/abhirupkumar/claude-code/blob/main/web/lib/api/client.ts): client-infra · Client API, collaboration sockets, export, search, storage, performance, and compatibility helpers. · `web/lib/api/client.ts`

### MCP server

Standalone source-explorer server package.

- [MCP server](https://github.com/abhirupkumar/claude-code/blob/main/mcp-server/src/index.ts): node-service · Standalone MCP package exposing source exploration and HTTP/server entrypoints. · `mcp-server/src/index.ts`
- [MCP HTTP](https://github.com/abhirupkumar/claude-code/blob/main/mcp-server/src/http.ts): transport · HTTP transport and server wiring for the MCP source-explorer package. · `mcp-server/src/http.ts`

## Connections

- CLI entry → Ink UI: launches · Bootstraps the terminal product and renders the Ink app.
- Ink UI → App state: reads/writes · UI components bind to shared application and session state.
- Ink UI → Input routing: captures input · Prompt box and keyboard handling feed normalized user input.
- Input routing → Commands: slash commands · Command input is dispatched to the control plane.
- Input routing → Query engine: prompt text · Natural-language input enters the agent loop.
- Query engine → Permission gate: checks · Tool proposals are filtered through approval and policy checks.
- Permission gate → Tool exec: allows · Approved tool calls proceed to execution.
- Query engine → Tool exec: requests · The agent loop issues tool calls and consumes streamed results.
- Tool exec → Tools: invokes · Execution targets the concrete tool modules.
- Query engine → App state: updates · Streaming turns and session state are reflected back into the UI state.
- Commands → Services: uses · Commands trigger auth, config, MCP, memory, plugin, and diagnostics services.
- Query engine → Services: depends on · Model calls and supporting infrastructure rely on shared services.
- Services → Memory & tasks: persists · Session memory and background work are managed through persistence services.
- IDE bridge → Services: syncs · Bridge sessions and editor callbacks rely on shared auth and session services.
- IDE bridge → Ink UI: coordinates · Editor/CLI synchronization affects terminal interaction and status views.
- Remote sessions → App state: hosts · Remote and web session infrastructure reflects the same session model.
- Remote sessions → Query engine: feeds · Remote sessions ultimately drive the same agent loop.
- Extensions → Tools: extends · Plugins and skills add capabilities to the tool and command surfaces.
- Extensions → Services: integrates · Extension loading and policy hooks depend on shared infrastructure.
- Web app shell → Web runtime: renders · The Next.js shell composes the browser-native UI.
- Web app shell → Web API: serves · The app exposes route handlers for chat, files, export, and share.
- Web runtime → Web lib: uses · UI components depend on shared client APIs and helpers.
- Web API → Web lib: delegates · Route handlers and browser workflows share data-access primitives.
- MCP server → MCP HTTP: hosts · The MCP package exposes source exploration over HTTP/server transport.
- MCP server → Services: adjacent to · The MCP package is separate but conceptually sits beside the main service layer.
