# jkspeaks/claude-code architecture

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

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

## Overview

#### Purpose and entry points
This repository archives the TypeScript source of Claude Code and adds exploration tooling around it. The primary product is a Bun-based terminal coding agent; companion surfaces include an MCP source-explorer server and a Next.js web UI.
- CLI/bootstrap: `src/main.tsx`, `src/entrypoints/cli.tsx`, `src/entrypoints/init.ts`
- MCP explorer executable/server: `mcp-server/src/index.ts`, `mcp-server/src/server.ts`
- Web surface: `web/app/page.tsx`, `web/app/api/chat/route.ts`

#### Interactive CLI and application state
The CLI parses invocation modes, initializes session/runtime dependencies, then renders a React terminal application using the repository’s Ink implementation. Application state, contexts, hooks, screens, commands, and components form the interactive control plane.
- Top-level UI and REPL: `src/components/App.tsx`, `src/screens/REPL.tsx`, `src/replLauncher.tsx`
- State and shared contexts: `src/state/AppState.tsx`, `src/state/AppStateStore.ts`, `src/context.ts`
- Custom terminal renderer: `src/ink/ink.tsx`, `src/ink/renderer.ts`, `src/ink/layout/engine.ts`

#### Model query pipeline
`QueryEngine` is the central agent loop: it builds model context, calls Claude-facing API services, handles streaming responses, coordinates tool calls/results, transitions, token budgets, retries, and session progression. Conversation history, compaction, memory extraction, and cost tracking constrain and preserve the session.
- Engine and query mechanics: `src/QueryEngine.ts`, `src/query/transitions.ts`, `src/query/tokenBudget.ts`
- API boundary: `src/services/api/claude.ts`, `src/services/api/client.ts`
- Context lifecycle: `src/context.ts`, `src/services/compact/compact.ts`, `src/services/SessionMemory/sessionMemory.ts`

#### Tools, safety, and execution
The model operates through a registered tool system spanning local files, shell/PowerShell, search, web access, LSP, MCP, tasks, and subagents. Tool orchestration is separated from permission decisions and concrete execution. Permission rules, path/shell validation, UI approvals, and sandbox support are the critical safety boundary before effects occur.
- Tool abstractions/registry: `src/Tool.ts`, `src/tools.ts`, `src/services/tools/toolOrchestration.ts`
- Representative effectful tools: `src/tools/BashTool/BashTool.tsx`, `src/tools/FileEditTool/FileEditTool.ts`, `src/tools/AgentTool/AgentTool.tsx`
- Authorization/sandbox boundary: `src/hooks/toolPermission/PermissionContext.ts`, `src/utils/permissions/permissions.ts`, `src/utils/sandbox/sandbox-adapter.ts`

#### Commands and extensibility
Slash commands provide user-directed operations separate from model tool calls: session control, configuration, authentication, review, MCP, plugins, tasks, and memory. Plugins, skills, and user-defined agents extend available commands, prompts, tools, output styles, hooks, and integrations.
- Command registry and implementations: `src/commands.ts`, `src/commands/mcp/mcp.tsx`, `src/commands/plugin/plugin.tsx`
- Plugin loading/install lifecycle: `src/services/plugins/PluginInstallationManager.ts`, `src/utils/plugins/pluginLoader.ts`
- Skills and agents: `src/skills/loadSkillsDir.ts`, `src/tools/AgentTool/loadAgentsDir.ts`

#### Remote, IDE, and multi-agent boundaries
The bridge subsystem runs bidirectional CLI–IDE sessions, including transport, JWT/trusted-device handling, inbound messages, and permission callbacks. Remote sessions and agent/team tasks provide alternate execution locations and asynchronous work while preserving task/session state.
- IDE bridge: `src/bridge/bridgeMain.ts`, `src/bridge/bridgeMessaging.ts`, `src/bridge/bridgePermissionCallbacks.ts`
- Remote control/session transport: `src/remote/RemoteSessionManager.ts`, `src/remote/SessionsWebSocket.ts`
- Task/teammate implementations: `src/tasks/LocalMainSessionTask.ts`, `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx`, `src/utils/swarm/spawnInProcess.ts`

#### External protocols, runtime, and deployment
Core runtime is Bun with strict TypeScript, React, and Ink; Zod schemas validate configuration/protocol inputs. External integrations include Anthropic APIs, OAuth/JWT and secure storage, MCP servers, LSP servers, GrowthBook/analytics, OpenTelemetry-style telemetry, GitHub, and optional cloud/remote services. Docker artifacts support container deployment; MCP server deployment includes Vercel and Railway-oriented files.
- Protocol services: `src/services/mcp/MCPConnectionManager.tsx`, `src/services/lsp/LSPServerManager.ts`, `src/services/oauth/client.ts`
- Telemetry/flags: `src/services/analytics/growthbook.ts`, `src/utils/telemetry/instrumentation.ts`
- Deployment: `Dockerfile`, `docker/docker-compose.yml`, `mcp-server/api/index.ts`

Main entry points: [`src/QueryEngine.ts`](https://github.com/jkspeaks/claude-code/blob/main/src/QueryEngine.ts) (Query engine), [`src/components/App.tsx`](https://github.com/jkspeaks/claude-code/blob/main/src/components/App.tsx) (Terminal app), [`src/screens/REPL.tsx`](https://github.com/jkspeaks/claude-code/blob/main/src/screens/REPL.tsx) (REPL), [`src/services/tools/toolOrchestration.ts`](https://github.com/jkspeaks/claude-code/blob/main/src/services/tools/toolOrchestration.ts) (Tool orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI Runtime"]
  node_bootstrap["CLI bootstrap<br/>entrypoint<br/>[main.tsx]"]
  node_cli["CLI modes<br/>entrypoint<br/>[cli.tsx]"]
  node_terminal_app["Terminal app<br/>Ink React UI<br/>[App.tsx]"]
  node_repl["REPL<br/>interactive screen<br/>[REPL.tsx]"]
  node_app_state["App state store<br/>[AppStateStore.ts]"]
  node_ink_renderer["Custom Ink renderer<br/>terminal renderer<br/>[renderer.ts]"]
end

subgraph group_agent["Agent Pipeline"]
  node_query_engine{{"Query engine<br/>agent loop<br/>[QueryEngine.ts]"}}
  node_context["Context lifecycle<br/>conversation context<br/>[context.ts]"]
  node_compaction["Compaction &amp; memory<br/>session preservation<br/>[compact.ts]"]
  node_claude_api["Claude API<br/>API boundary<br/>[claude.ts]"]
end

subgraph group_tools["Tools &amp; Safety"]
  node_tool_registry["Tool registry<br/>tool abstractions<br/>[tools.ts]"]
  node_tool_orchestration["Tool orchestration<br/>tool coordinator"]
  node_permissions{{"Permission boundary<br/>authorization &amp; sandbox<br/>[permissions.ts]"}}
  node_effectful_tools["Effectful tools<br/>[BashTool.tsx]"]
end

subgraph group_extensions["Extensions &amp; Protocols"]
  node_commands["Slash commands<br/>command registry<br/>[commands.ts]"]
  node_plugins["Plugin lifecycle<br/>extension loader"]
  node_protocol_managers["MCP &amp; LSP managers<br/>protocol integrations"]
end

subgraph group_surfaces["Companion Surfaces"]
  node_mcp_explorer["MCP explorer server<br/>MCP server<br/>[index.ts]"]
  node_web["Web UI &amp; chat API<br/>Next.js surface<br/>[page.tsx]"]
  node_ide_bridge["IDE bridge<br/>bidirectional bridge<br/>[bridgeMain.ts]"]
  node_remote_sessions["Remote sessions &amp; tasks<br/>remote execution"]
  node_deployment["Container deployment<br/>Docker deployment"]
end

node_bootstrap -->|"starts"| node_cli
node_cli -->|"renders"| node_terminal_app
node_terminal_app -->|"hosts"| node_repl
node_terminal_app -->|"uses"| node_app_state
node_terminal_app -->|"renders through"| node_ink_renderer
node_repl -->|"submits prompts"| node_query_engine
node_repl -->|"dispatches slash commands"| node_commands
node_query_engine -->|"builds"| node_context
node_query_engine -->|"maintains history"| node_compaction
node_query_engine -->|"streams queries"| node_claude_api
node_query_engine -->|"coordinates tool calls"| node_tool_orchestration
node_tool_orchestration -->|"resolves tools"| node_tool_registry
node_tool_orchestration -->|"requests authorization"| node_permissions
node_permissions -->|"gates effects"| node_effectful_tools
node_commands -->|"manages extensions"| node_plugins
node_plugins -.->|"extends"| node_tool_registry
node_protocol_managers -.->|"provides protocol tools"| node_tool_registry
node_commands -->|"configures"| node_protocol_managers
node_ide_bridge -->|"forwards approvals"| node_permissions
node_remote_sessions -.->|"hosts alternate sessions"| node_query_engine
node_web -.->|"chat surface"| node_query_engine
node_deployment -.->|"packages CLI runtime"| node_bootstrap

click node_bootstrap "https://github.com/jkspeaks/claude-code/blob/main/src/main.tsx"
click node_cli "https://github.com/jkspeaks/claude-code/blob/main/src/entrypoints/cli.tsx"
click node_terminal_app "https://github.com/jkspeaks/claude-code/blob/main/src/components/App.tsx"
click node_repl "https://github.com/jkspeaks/claude-code/blob/main/src/screens/REPL.tsx"
click node_app_state "https://github.com/jkspeaks/claude-code/blob/main/src/state/AppStateStore.ts"
click node_ink_renderer "https://github.com/jkspeaks/claude-code/blob/main/src/ink/renderer.ts"
click node_query_engine "https://github.com/jkspeaks/claude-code/blob/main/src/QueryEngine.ts"
click node_context "https://github.com/jkspeaks/claude-code/blob/main/src/context.ts"
click node_compaction "https://github.com/jkspeaks/claude-code/blob/main/src/services/compact/compact.ts"
click node_claude_api "https://github.com/jkspeaks/claude-code/blob/main/src/services/api/claude.ts"
click node_tool_registry "https://github.com/jkspeaks/claude-code/blob/main/src/tools.ts"
click node_tool_orchestration "https://github.com/jkspeaks/claude-code/blob/main/src/services/tools/toolOrchestration.ts"
click node_permissions "https://github.com/jkspeaks/claude-code/blob/main/src/utils/permissions/permissions.ts"
click node_effectful_tools "https://github.com/jkspeaks/claude-code/blob/main/src/tools/BashTool/BashTool.tsx"
click node_commands "https://github.com/jkspeaks/claude-code/blob/main/src/commands.ts"
click node_plugins "https://github.com/jkspeaks/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts"
click node_protocol_managers "https://github.com/jkspeaks/claude-code/blob/main/src/services/mcp/MCPConnectionManager.tsx"
click node_mcp_explorer "https://github.com/jkspeaks/claude-code/blob/main/mcp-server/src/index.ts"
click node_web "https://github.com/jkspeaks/claude-code/blob/main/web/app/page.tsx"
click node_ide_bridge "https://github.com/jkspeaks/claude-code/blob/main/src/bridge/bridgeMain.ts"
click node_remote_sessions "https://github.com/jkspeaks/claude-code/blob/main/src/remote/RemoteSessionManager.ts"
click node_deployment "https://github.com/jkspeaks/claude-code/blob/main/Dockerfile"

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_bootstrap,node_cli,node_terminal_app,node_repl,node_app_state,node_ink_renderer toneBlue
class node_query_engine,node_context,node_compaction,node_claude_api toneAmber
class node_tool_registry,node_tool_orchestration,node_permissions,node_effectful_tools toneMint
class node_commands,node_plugins,node_protocol_managers toneRose
class node_mcp_explorer,node_web,node_ide_bridge,node_remote_sessions,node_deployment toneIndigo
```

## Components

### CLI Runtime

Bun terminal-agent control plane.

- [CLI bootstrap](https://github.com/jkspeaks/claude-code/blob/main/src/main.tsx): entrypoint · `src/main.tsx`
- [CLI modes](https://github.com/jkspeaks/claude-code/blob/main/src/entrypoints/cli.tsx): entrypoint · `src/entrypoints/cli.tsx`
- [Terminal app](https://github.com/jkspeaks/claude-code/blob/main/src/components/App.tsx): Ink React UI · Top-level interactive application. · `src/components/App.tsx`
- [REPL](https://github.com/jkspeaks/claude-code/blob/main/src/screens/REPL.tsx): interactive screen · `src/screens/REPL.tsx`
- [App state store](https://github.com/jkspeaks/claude-code/blob/main/src/state/AppStateStore.ts): state · Shared session and UI state. · `src/state/AppStateStore.ts`
- [Custom Ink renderer](https://github.com/jkspeaks/claude-code/blob/main/src/ink/renderer.ts): terminal renderer · `src/ink/renderer.ts`

### Agent Pipeline

Model context, querying, and session lifecycle.

- [Query engine](https://github.com/jkspeaks/claude-code/blob/main/src/QueryEngine.ts): agent loop · Coordinates streaming, tools, retries, budgets, and progression. · `src/QueryEngine.ts`
- [Context lifecycle](https://github.com/jkspeaks/claude-code/blob/main/src/context.ts): conversation context · `src/context.ts`
- [Compaction & memory](https://github.com/jkspeaks/claude-code/blob/main/src/services/compact/compact.ts): session preservation · `src/services/compact/compact.ts`
- [Claude API](https://github.com/jkspeaks/claude-code/blob/main/src/services/api/claude.ts): API boundary · `src/services/api/claude.ts`

### Tools & Safety

Effect execution is gated by permissions.

- [Tool registry](https://github.com/jkspeaks/claude-code/blob/main/src/tools.ts): tool abstractions · `src/tools.ts`
- [Tool orchestration](https://github.com/jkspeaks/claude-code/blob/main/src/services/tools/toolOrchestration.ts): tool coordinator · `src/services/tools/toolOrchestration.ts`
- [Permission boundary](https://github.com/jkspeaks/claude-code/blob/main/src/utils/permissions/permissions.ts): authorization & sandbox · Validates paths and shell effects before execution. · `src/utils/permissions/permissions.ts`
- [Effectful tools](https://github.com/jkspeaks/claude-code/blob/main/src/tools/BashTool/BashTool.tsx): file, shell & agent tools · `src/tools/BashTool/BashTool.tsx`

### Extensions & Protocols

Commands and external integration managers.

- [Slash commands](https://github.com/jkspeaks/claude-code/blob/main/src/commands.ts): command registry · `src/commands.ts`
- [Plugin lifecycle](https://github.com/jkspeaks/claude-code/blob/main/src/services/plugins/PluginInstallationManager.ts): extension loader · Loads plugins, skills, and user agents. · `src/services/plugins/PluginInstallationManager.ts`
- [MCP & LSP managers](https://github.com/jkspeaks/claude-code/blob/main/src/services/mcp/MCPConnectionManager.tsx): protocol integrations · `src/services/mcp/MCPConnectionManager.tsx`

### Companion Surfaces

Explorer, web, IDE, and remote entry points.

- [MCP explorer server](https://github.com/jkspeaks/claude-code/blob/main/mcp-server/src/index.ts): MCP server · Source-explorer executable and server. · `mcp-server/src/index.ts`
- [Web UI & chat API](https://github.com/jkspeaks/claude-code/blob/main/web/app/page.tsx): Next.js surface · `web/app/page.tsx`
- [IDE bridge](https://github.com/jkspeaks/claude-code/blob/main/src/bridge/bridgeMain.ts): bidirectional bridge · CLI–IDE transport with permission callbacks. · `src/bridge/bridgeMain.ts`
- [Remote sessions & tasks](https://github.com/jkspeaks/claude-code/blob/main/src/remote/RemoteSessionManager.ts): remote execution · `src/remote/RemoteSessionManager.ts`
- [Container deployment](https://github.com/jkspeaks/claude-code/blob/main/Dockerfile): Docker deployment · `Dockerfile`

## Connections

- CLI bootstrap → CLI modes: starts
- CLI modes → Terminal app: renders
- Terminal app → REPL: hosts
- Terminal app → App state store: uses
- Terminal app → Custom Ink renderer: renders through
- REPL → Query engine: submits prompts
- REPL → Slash commands: dispatches slash commands
- Query engine → Context lifecycle: builds
- Query engine → Compaction & memory: maintains history
- Query engine → Claude API: streams queries
- Query engine → Tool orchestration: coordinates tool calls
- Tool orchestration → Tool registry: resolves tools
- Tool orchestration → Permission boundary: requests authorization
- Permission boundary → Effectful tools: gates effects
- Slash commands → Plugin lifecycle: manages extensions
- Plugin lifecycle → Tool registry: extends
- MCP & LSP managers → Tool registry: provides protocol tools
- Slash commands → MCP & LSP managers: configures
- IDE bridge → Permission boundary: forwards approvals
- Remote sessions & tasks → Query engine: hosts alternate sessions
- Web UI & chat API → Query engine: chat surface
- Container deployment → CLI bootstrap: packages CLI runtime