# nirholas/claude-code architecture

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

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

## Overview

1. This repo is a Bun/TypeScript monorepo centered on a terminal-first Claude Code client, with two major adjacent deliverables: a Next.js-based web companion app under `web/` and a separate MCP explorer server under `mcp-server/`. The core product lives in `src/`.

2. The main runtime path starts at `src/main.tsx` and the `src/entrypoints/*` modules. Startup does environment/bootstrap work, loads settings and auth state, initializes feature flags/telemetry, then mounts the React + Ink terminal UI from `src/components/` and `src/ink/`.

3. The central control loop is the query pipeline: `src/QueryEngine.ts` plus `src/query/` and `src/services/tools/`. This is where user prompts become LLM requests, streaming responses, tool calls, retries, token accounting, and turn transitions. It is the orchestration boundary for “assistant talks, decides, uses tools, continues.”

4. Tool execution is a first-class subsystem. Each tool in `src/tools/*` owns its schema, UI, permission expectations, and execution logic. The main categories are file editing/search, shell execution, web access, MCP/LSP access, sub-agents, task/team coordination, and mode/state toggles like plan mode or worktree mode.

5. Permissions are enforced as a cross-cutting boundary rather than a single gate. `src/hooks/toolPermission/` and `src/utils/permissions/` decide whether a tool action is allowed, denied, or escalated to user approval, with special handling for shell/file operations, plan mode, sandboxing, and bypass/auto modes. This layer sits directly in the tool invocation path.

6. The UI is split between an Ink terminal app and reusable UI primitives. `src/components/` contains the terminal screens, dialogs, permission prompts, task views, command palettes, and message renderers, while `src/ink/` provides the custom terminal renderer/runtime that powers the TUI. The state driving these views lives in `src/state/`, `src/context/`, and hooks under `src/hooks/`.

7. Slash commands are another major entry path. `src/commands.ts` registers the command set, and `src/commands/*` implements discrete workflows such as `/review`, `/compact`, `/config`, `/mcp`, `/memory`, `/tasks`, `/resume`, `/doctor`, `/share`, and `/desktop`. Commands are user-facing orchestration, usually calling into the same services and state as the main chat loop.

8. External integration logic is concentrated in `src/services/`. This includes Anthropic API access, OAuth, analytics/feature flags, LSP management, MCP connection management, plugin loading, compacting conversations, memory extraction/sync, policy limits, and managed settings. These services form the “infrastructure layer” beneath both commands and tools.

9. IDE and REPL collaboration runs through the bridge subsystem in `src/bridge/`. That layer provides bidirectional messaging, session control, permission callbacks, JWT/auth helpers, and REPL bridge transport so external editors like VS Code or JetBrains can coordinate with the CLI session.

10. The repo supports multi-agent and background work through several connected subsystems: `src/coordinator/`, `src/tasks/`, `src/tools/AgentTool`, `src/services/tools/`, and `src/utils/swarm/`. Together they model local shell tasks, remote agent tasks, in-process teammates, agent spawning, task lifecycle, and team/multi-worker coordination.

11. Persistence and session continuity are handled by `src/utils/session*`, `src/history.ts`, `src/memdir/`, `src/services/teamMemorySync/`, and remote/session code under `src/remote/` and `src/server/`. This is where conversation history, memory files, resumable sessions, remote session transport, and server-side session management are kept separate from the live query loop.

12. Plugins, skills, and output styling extend the core without changing it. `src/plugins/` and `src/skills/` load user/bundled extensions; `src/outputStyles/` adjusts presentation; `src/constants/` and `src/schemas/` define shared configuration and validation contracts. This keeps extension points modular around the core tool/query pipeline.

13. The `web/` package is a companion client, not a thin asset bundle. It has its own API routes for chat, export, file read/write, and share, plus a collaboration layer, notifications, file viewer, and streaming/chat UI. It likely consumes the same conversation/file/session concepts as the CLI, but through HTTP and browser state instead of Ink.

14. Operationally, the repo is built around local execution plus external services: Anthropic for model calls, GrowthBook/analytics for feature flags and telemetry, OAuth/JWT/keychain for auth, LSP/MCP for tool ecosystems, and Git/GitHub for repo-aware workflows. For an architecture diagram, the main boundaries are: terminal UI, query/tool orchestration, permission gate, service integrations, bridge/remote transport, and the separate web/MCP packages.

Main entry points: [`src/QueryEngine.ts`](https://github.com/nirholas/claude-code/blob/main/src/QueryEngine.ts) (Query engine), [`src/services`](https://github.com/nirholas/claude-code/tree/main/src/services) (Services), [`scripts`](https://github.com/nirholas/claude-code/tree/main/scripts) (Build scripts), [`web/app`](https://github.com/nirholas/claude-code/tree/main/web/app) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core CLI"]
  node_src_main(("Main entry<br/>bootstrap<br/>[main.tsx]"))
  node_src_entrypoints["Entrypoints<br/>runtime entry"]
  node_src_query{{"Query engine<br/>orchestrator<br/>[QueryEngine.ts]"}}
  node_src_tools["Tools<br/>execution layer"]
  node_src_permissions{{"Permissions<br/>policy gate"}}
  node_src_ui["TUI + UI<br/>terminal ui"]
  node_src_commands["Slash commands<br/>user workflows<br/>[commands.ts]"]
  node_src_services["Services<br/>infrastructure"]
  node_src_bridge["Bridge"]
  node_src_swarm["Tasks + swarm<br/>multi-agent"]
  node_src_state["State + context<br/>app state"]
  node_src_utils["Shared utils<br/>foundation"]
end

subgraph group_web["Web Companion"]
  node_web_app["Web app<br/>next.js client"]
  node_web_lib["Web libs<br/>browser infra"]
  node_web_ui["Web UI<br/>browser ui"]
end

subgraph group_mcp["MCP Server"]
  node_mcp_server_pkg["MCP server<br/>standalone service"]
end

subgraph group_ops["Shared Infra"]
  node_build_scripts["Build scripts<br/>tooling"]
  node_root_config["Repo config<br/>workspace config<br/>[package.json]"]
end

node_src_main -->|"boots via"| node_src_entrypoints
node_src_entrypoints -->|"starts loop"| node_src_query
node_src_query -->|"invokes tools"| node_src_tools
node_src_tools -->|"checks access"| node_src_permissions
node_src_permissions -->|"prompts user"| node_src_ui
node_src_query -->|"uses services"| node_src_services
node_src_commands -->|"calls workflows"| node_src_services
node_src_commands -->|"shares loop"| node_src_query
node_src_ui -->|"reads state"| node_src_state
node_src_state -->|"built on"| node_src_utils
node_src_bridge -->|"integrates"| node_src_services
node_src_bridge -->|"coordinates"| node_src_query
node_src_swarm -->|"spawns work"| node_src_tools
node_src_swarm -->|"polls permissions"| node_src_permissions
node_web_app -->|"uses"| node_web_lib
node_web_app -->|"renders"| node_web_ui
node_web_ui -->|"drives"| node_web_lib
node_mcp_server_pkg -.->|"bridges to core"| node_src_services
node_build_scripts -->|"orchestrates"| node_root_config
node_build_scripts -->|"builds"| node_web_app
node_build_scripts -->|"packages"| node_mcp_server_pkg

click node_src_main "https://github.com/nirholas/claude-code/blob/main/src/main.tsx"
click node_src_entrypoints "https://github.com/nirholas/claude-code/tree/main/src/entrypoints"
click node_src_query "https://github.com/nirholas/claude-code/blob/main/src/QueryEngine.ts"
click node_src_tools "https://github.com/nirholas/claude-code/tree/main/src/tools"
click node_src_permissions "https://github.com/nirholas/claude-code/tree/main/src/hooks/toolPermission"
click node_src_ui "https://github.com/nirholas/claude-code/tree/main/src/components"
click node_src_commands "https://github.com/nirholas/claude-code/blob/main/src/commands.ts"
click node_src_services "https://github.com/nirholas/claude-code/tree/main/src/services"
click node_src_bridge "https://github.com/nirholas/claude-code/tree/main/src/bridge"
click node_src_swarm "https://github.com/nirholas/claude-code/tree/main/src/tasks"
click node_src_state "https://github.com/nirholas/claude-code/tree/main/src/state"
click node_src_utils "https://github.com/nirholas/claude-code/tree/main/src/utils"
click node_web_app "https://github.com/nirholas/claude-code/tree/main/web/app"
click node_web_lib "https://github.com/nirholas/claude-code/tree/main/web/lib"
click node_web_ui "https://github.com/nirholas/claude-code/tree/main/web/components"
click node_mcp_server_pkg "https://github.com/nirholas/claude-code/tree/main/mcp-server/src"
click node_build_scripts "https://github.com/nirholas/claude-code/tree/main/scripts"
click node_root_config "https://github.com/nirholas/claude-code/blob/main/package.json"

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_src_main,node_src_entrypoints,node_src_query,node_src_tools,node_src_permissions,node_src_ui,node_src_commands,node_src_services,node_src_bridge,node_src_swarm,node_src_state,node_src_utils toneBlue
class node_web_app,node_web_lib,node_web_ui toneAmber
class node_mcp_server_pkg toneMint
class node_build_scripts,node_root_config toneRose
```

## Components

### Core CLI

Terminal-first Claude Code client and its orchestration/runtime layers.

- [Main entry](https://github.com/nirholas/claude-code/blob/main/src/main.tsx): bootstrap · Starts the Bun app, performs startup/bootstrap, and mounts the terminal UI. · `src/main.tsx`
- [Entrypoints](https://github.com/nirholas/claude-code/tree/main/src/entrypoints): runtime entry · CLI, init, MCP, and SDK-facing entry modules that fan into the core app. · `src/entrypoints`
- [Query engine](https://github.com/nirholas/claude-code/blob/main/src/QueryEngine.ts): orchestrator · Central assistant loop: prompt handling, streaming turns, retries, tool calls, and token/turn transitions. · `src/QueryEngine.ts`
- [Tools](https://github.com/nirholas/claude-code/tree/main/src/tools): execution layer · All tool implementations and schemas for file, shell, web, MCP/LSP, agents, tasks, and mode toggles. · `src/tools`
- [Permissions](https://github.com/nirholas/claude-code/tree/main/src/hooks/toolPermission): policy gate · Cross-cutting tool approval, denial, and escalation logic for shell, file, sandbox, and auto modes. · `src/hooks/toolPermission`
- [TUI + UI](https://github.com/nirholas/claude-code/tree/main/src/components): terminal ui · Ink runtime, reusable React components, prompts, dialogs, and message renderers for the terminal client. · `src/components`
- [Slash commands](https://github.com/nirholas/claude-code/blob/main/src/commands.ts): user workflows · Command registry and discrete workflows such as review, compact, config, mcp, memory, tasks, resume, and desktop. · `src/commands.ts`
- [Services](https://github.com/nirholas/claude-code/tree/main/src/services): infrastructure · Model API, auth, analytics, MCP/LSP, plugin, memory, compacting, policy, voice, and other shared integrations. · `src/services`
- [Bridge](https://github.com/nirholas/claude-code/tree/main/src/bridge): ide bridge · Bidirectional editor/REPL bridge with session control, messaging, permissions, and auth helpers. · `src/bridge`
- [Tasks + swarm](https://github.com/nirholas/claude-code/tree/main/src/tasks): multi-agent · Background tasks, teammates, coordinator logic, and swarm utilities for local and remote parallel work. · `src/tasks`
- [State + context](https://github.com/nirholas/claude-code/tree/main/src/state): app state · Application state, context providers, stores, and selectors that drive the UI and execution flow. · `src/state`
- [Shared utils](https://github.com/nirholas/claude-code/tree/main/src/utils): foundation · Repository-wide helpers for sessions, permissions, prompts, files, git, telemetry, plugins, and runtime plumbing. · `src/utils`

### Web Companion

Next.js browser client and API surface.

- [Web app](https://github.com/nirholas/claude-code/tree/main/web/app): next.js client · Browser companion app with its own API routes, chat UI, collaboration, file viewing, and export surfaces. · `web/app`
- [Web libs](https://github.com/nirholas/claude-code/tree/main/web/lib): browser infra · Client-side API adapters, stores, collaboration, performance, search, export, and compatibility helpers. · `web/lib`
- [Web UI](https://github.com/nirholas/claude-code/tree/main/web/components): browser ui · Chat, file viewer, command palette, settings, notifications, and shared browser components. · `web/components`

### MCP Server

Standalone MCP explorer/server package.

- [MCP server](https://github.com/nirholas/claude-code/tree/main/mcp-server/src): standalone service · Separate MCP explorer/server package with HTTP/server bootstrapping. · `mcp-server/src`

### Shared Infra

Build, packaging, and repository-level tooling.

- [Build scripts](https://github.com/nirholas/claude-code/tree/main/scripts): tooling · Repository scripts for bundling, dev, testing, packaging, and CI builds. · `scripts`
- [Repo config](https://github.com/nirholas/claude-code/blob/main/package.json): workspace config · Top-level package, lockfile, Docker, CI, and deployment configuration. · `package.json`

## Connections

- Main entry → Entrypoints: boots via · Startup routes through CLI/init/MCP entrypoints before the app is mounted.
- Entrypoints → Query engine: starts loop · Entrypoints initialize and hand control to the query orchestration pipeline.
- Query engine → Tools: invokes tools · The assistant loop dispatches tool schemas and execution requests.
- Tools → Permissions: checks access · Tool execution consults the permission gate before performing sensitive actions.
- Permissions → TUI + UI: prompts user · Denied or escalated actions surface approval dialogs and permission UI.
- Query engine → Services: uses services · Query orchestration depends on model, memory, compacting, and infrastructure services.
- Slash commands → Services: calls workflows · Slash commands reuse service-layer integrations and orchestration helpers.
- Slash commands → Query engine: shares loop · Many commands delegate back into the same core assistant/session machinery.
- TUI + UI → State + context: reads state · Screens and dialogs are driven by centralized app state and context providers.
- State + context → Shared utils: built on · State management depends on shared session, prompt, permission, and persistence utilities.
- Bridge → Services: integrates · Bridge sessions reuse auth, session, and messaging services.
- Bridge → Query engine: coordinates · External editors and REPL sessions coordinate with the live assistant loop.
- Tasks + swarm → Tools: spawns work · Agent/task coordination uses tool execution to perform background work.
- Tasks + swarm → Permissions: polls permissions · Multi-agent and worker flows still pass through the same approval model.
- Web app → Web libs: uses · Server routes and browser pages share client, export, collaboration, and store logic.
- Web app → Web UI: renders · The Next.js app is assembled from browser UI components and layouts.
- Web UI → Web libs: drives · UI components depend on shared browser libraries, stores, and helpers.
- MCP server → Services: bridges to core · The standalone MCP server relies on shared service/integration patterns from the main repo.
- Build scripts → Repo config: orchestrates · Scripts are governed by the workspace package and deployment configuration.
- Build scripts → Web app: builds · One script path specifically builds the web companion package.
- Build scripts → MCP server: packages · Separate scripts and workflows produce the MCP server artifacts.
