# roger2ai/claude-code-compiled architecture

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

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

## Overview

1. **This is a Bun-based terminal application, not a web app.**  
   The main runtime is TypeScript compiled with Bun, with the user interface built on a custom Ink/React terminal renderer in `src/ink` and `src/components`. The primary entrypoint is `src/main.tsx`, with CLI bootstrapping and SDK entrypoints in `src/entrypoints/*`.

2. **Startup flows through a small boot layer into a large app state tree.**  
   `src/bootstrap`, `src/setup.ts`, `src/state`, and `src/context` initialize configuration, auth, session state, keybindings, and UI context before the main REPL or command screen renders. The app is state-driven: most UI and behavior read from `AppState`/selectors rather than communicating point-to-point.

3. **The core interaction loop is prompt → model query → tool calls → rendered messages.**  
   `src/QueryEngine.ts`, `src/query/*`, `src/services/tools/*`, and `src/utils/messages/*` form the main execution path. User input is normalized, turned into a model request, the model may request tool execution, and the resulting tool outputs are converted into message objects and displayed in the conversation timeline.

4. **Tools are the main boundary between the assistant and the local environment.**  
   The `src/tools/*` tree contains the concrete tool implementations: shell execution, file read/write/edit, grep/glob, web fetch/search, notebook editing, MCP invocation, sub-agents, task management, and more. Each tool has its own UI wrapper, prompt/schema, and validation/security helpers, which keeps model-facing behavior separate from execution details.

5. **Permissioning and sandboxing sit in front of destructive or sensitive actions.**  
   `src/hooks/toolPermission`, `src/components/permissions`, `src/utils/permissions`, `src/services/mcpServerApproval.tsx`, and `src/utils/sandbox/*` gate tool use. This layer decides whether a tool runs directly, requires user approval, or is blocked, and it also handles shell safety, filesystem allowlists, and sandbox selection.

6. **The terminal UI is a composition of screens, dialogs, and message renderers.**  
   `src/screens/*` hosts full-screen modes like REPL, Doctor, and Resume Conversation. `src/components/*` contains the conversation UI, prompt box, status line, dialogs, onboarding, model picker, permission prompts, and specialized message renderers. The UI layer is highly modular but ultimately driven by the same conversation/state store.

7. **Commands are a large plugin-like command system layered over the CLI.**  
   `src/commands/*` defines the slash commands and top-level command handlers, including session management, config, login/logout, plugins, MCP, review, resume, and many specialized workflows. This command layer is the user’s main control surface for changing app behavior, not just a thin argument parser.

8. **Skills and plugins extend the assistant with packaged behavior.**  
   `src/skills/*` and `src/plugins/*` provide bundled skills, loaded skills directories, plugin commands, marketplace flows, validation, and autoupdate logic. These systems plug into tools, prompts, and UI, but remain separate from the core model loop so they can be enabled/disabled or reloaded independently.

9. **Remote, bridge, and IDE integration form a separate control plane.**  
   `src/bridge/*`, `src/remote/*`, `src/server/*`, `src/upstreamproxy/*`, and related hooks handle IDE handoff, remote sessions, session relays, and bridge messaging. This is distinct from the local REPL: it synchronizes session state, permissions, attachments, and commands across processes or devices.

10. **There is a second orchestration layer for background work and multi-agent/task management.**  
   `src/tasks/*`, `src/utils/tasks.ts`, `src/tools/Task*`, `src/tools/AgentTool/*`, `src/utils/swarm/*`, and `src/services/autoDream/*` manage local shell tasks, remote agent tasks, subagents, team/teammate flows, and background jobs. These flows are decoupled from the main conversation loop but feed status and outputs back into the shared message/task UI.

11. **External service integration is concentrated in service modules.**  
   `src/services/api/*` talks to Anthropic APIs and account-related endpoints; `src/services/oauth/*` handles auth flows; `src/services/analytics/*` handles telemetry; `src/services/mcp/*` manages MCP connections; `src/services/lsp/*` manages language servers; `src/services/voice*` handles voice features. These modules isolate networked concerns from the assistant core.

12. **Persistence is split across session storage, caches, memories, and settings.**  
   `src/utils/sessionStorage*`, `src/utils/settings/*`, `src/memdir/*`, `src/utils/filePersistence/*`, `src/utils/cachePaths.ts`, and related utilities handle conversation history, user settings, memories, tool outputs, and derived caches. The repo treats these as durable local state that can be restored, migrated, and synchronized.

13. **The repo includes a substantial low-level terminal/rendering subsystem.**  
   `src/ink/*` is effectively its own renderer and event system: layout, hit testing, input handling, terminal focus, frame generation, ANSI output, and selection/cursor management. This is the foundation that lets the assistant feel like a native TUI instead of a simple stdout printer.

14. **Build-time compatibility shims and feature gates are part of the architecture.**  
   `shims/macro.ts` and `shims/bun-bundle.ts` replace Bun/internal build features, while `feature()`-style gating and migrations in `src/migrations/*` control which experimental subsystems are live. This repo is intentionally structured so unsupported/internal features can be tree-shaken or stubbed without breaking the core CLI.

15. **A practical diagram should show three main boundaries: UI/runtime, orchestration, and integrations.**  
   On one side are the Ink UI and command surfaces; in the middle are state, query/turn execution, tools, permissions, tasks, and session orchestration; on the other side are Anthropic APIs, OAuth, MCP/LSP/analytics, filesystem/shell, and remote bridge endpoints. Most flows are: user input → state/command routing → model/tool execution → message rendering, with separate side channels for auth, sync, telemetry, and remote control.

Main entry points: [`src/QueryEngine.ts`](https://github.com/roger2ai/claude-code-compiled/blob/main/src/QueryEngine.ts) (Query loop), [`src/tools`](https://github.com/roger2ai/claude-code-compiled/tree/main/src/tools) (Tools), [`src/state`](https://github.com/roger2ai/claude-code-compiled/tree/main/src/state) (App state), [`src/components`](https://github.com/roger2ai/claude-code-compiled/tree/main/src/components) (UI components)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & UI"]
  node_main(("Main entry<br/>entrypoint<br/>[main.tsx]"))
  node_entrypoints["CLI entrypoints<br/>cli bootstrap"]
  node_ink["Ink renderer<br/>tui renderer"]
  node_screens["Screens<br/>full-screen modes"]
  node_components["UI components<br/>tui views"]
end

subgraph group_orchestration["Orchestration"]
  node_appstate[("App state<br/>state store")]
  node_bootstrap["Bootstrap<br/>init layer"]
  node_queryloop{{"Query loop<br/>turn engine<br/>[QueryEngine.ts]"}}
  node_commands["Commands<br/>slash command system"]
  node_tasks["Tasks<br/>background work"]
  node_skillsplugins["Skills & plugins<br/>extensions"]
end

subgraph group_execution["Execution & Safety"]
  node_tools["Tools<br/>tool implementations"]
  node_permissions{{"Permissions<br/>approval & sandbox"}}
  node_messages["Messages<br/>message model"]
end

subgraph group_integrations["Integrations"]
  node_services["Services"]
  node_bridge["Bridge layer<br/>remote control plane"]
  node_remote["Remote control<br/>session relay"]
end

subgraph group_platform["Platform"]
  node_storage[("Persistence<br/>local durable state<br/>[sessionStorage.ts]")]
  node_utils["Core utils<br/>shared utilities"]
  node_shims["Build shims<br/>compatibility"]
end

node_main -->|"boots"| node_entrypoints
node_main -->|"initializes"| node_bootstrap
node_bootstrap -->|"hydrates"| node_appstate
node_entrypoints -->|"routes"| node_commands
node_entrypoints -->|"starts"| node_queryloop
node_queryloop -->|"requests tools"| node_tools
node_permissions -->|"gates"| node_tools
node_tools -->|"emits"| node_messages
node_queryloop -->|"produces"| node_messages
node_messages -->|"renders in"| node_components
node_appstate -->|"drives"| node_components
node_ink -->|"hosts"| node_components
node_screens -->|"wraps"| node_queryloop
node_commands -->|"updates"| node_appstate
node_commands -->|"controls"| node_tasks
node_skillsplugins -->|"extends"| node_tools
node_skillsplugins -->|"adds commands"| node_commands
node_services -->|"supports"| node_queryloop
node_services -->|"backs"| node_tools
node_bridge -->|"connects"| node_remote
node_bridge -->|"syncs"| node_appstate
node_storage -->|"persists"| node_appstate
node_utils -->|"supports"| node_queryloop
node_utils -->|"supports"| node_tools
node_shims -.->|"enables build"| node_main
node_shims -.->|"enables build"| node_ink
node_tasks -->|"surfaces status"| node_components
node_permissions -->|"prompts"| node_components

click node_main "https://github.com/roger2ai/claude-code-compiled/blob/main/src/main.tsx"
click node_entrypoints "https://github.com/roger2ai/claude-code-compiled/tree/main/src/entrypoints"
click node_ink "https://github.com/roger2ai/claude-code-compiled/tree/main/src/ink"
click node_screens "https://github.com/roger2ai/claude-code-compiled/tree/main/src/screens"
click node_components "https://github.com/roger2ai/claude-code-compiled/tree/main/src/components"
click node_appstate "https://github.com/roger2ai/claude-code-compiled/tree/main/src/state"
click node_bootstrap "https://github.com/roger2ai/claude-code-compiled/tree/main/src/bootstrap"
click node_queryloop "https://github.com/roger2ai/claude-code-compiled/blob/main/src/QueryEngine.ts"
click node_commands "https://github.com/roger2ai/claude-code-compiled/tree/main/src/commands"
click node_tasks "https://github.com/roger2ai/claude-code-compiled/tree/main/src/tasks"
click node_skillsplugins "https://github.com/roger2ai/claude-code-compiled/tree/main/src/skills"
click node_tools "https://github.com/roger2ai/claude-code-compiled/tree/main/src/tools"
click node_permissions "https://github.com/roger2ai/claude-code-compiled/tree/main/src/hooks/toolPermission"
click node_messages "https://github.com/roger2ai/claude-code-compiled/tree/main/src/utils/messages"
click node_services "https://github.com/roger2ai/claude-code-compiled/tree/main/src/services"
click node_bridge "https://github.com/roger2ai/claude-code-compiled/tree/main/src/bridge"
click node_remote "https://github.com/roger2ai/claude-code-compiled/tree/main/src/remote"
click node_storage "https://github.com/roger2ai/claude-code-compiled/blob/main/src/utils/sessionStorage.ts"
click node_utils "https://github.com/roger2ai/claude-code-compiled/tree/main/src/utils"
click node_shims "https://github.com/roger2ai/claude-code-compiled/tree/main/shims"

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,node_entrypoints,node_ink,node_screens,node_components toneBlue
class node_appstate,node_bootstrap,node_queryloop,node_commands,node_tasks,node_skillsplugins toneAmber
class node_tools,node_permissions,node_messages toneMint
class node_services,node_bridge,node_remote toneRose
class node_storage,node_utils,node_shims toneIndigo
```

## Components

### Runtime & UI

Bun entrypoints, Ink renderer, screens, components, and input handling.

- [Main entry](https://github.com/roger2ai/claude-code-compiled/blob/main/src/main.tsx): entrypoint · Top-level Bun/TypeScript startup and CLI bootstrapping. · `src/main.tsx`
- [CLI entrypoints](https://github.com/roger2ai/claude-code-compiled/tree/main/src/entrypoints): cli bootstrap · CLI, init, MCP, and SDK entrypoints that wire process-level modes. · `src/entrypoints`
- [Ink renderer](https://github.com/roger2ai/claude-code-compiled/tree/main/src/ink): tui renderer · Custom terminal rendering, layout, focus, events, and screen output. · `src/ink`
- [Screens](https://github.com/roger2ai/claude-code-compiled/tree/main/src/screens): full-screen modes · REPL, Doctor, and Resume Conversation screen flows. · `src/screens`
- [UI components](https://github.com/roger2ai/claude-code-compiled/tree/main/src/components): tui views · Conversation UI, dialogs, message renderers, prompts, and specialized panes. · `src/components`

### Orchestration

App state, query loop, commands, tasks, skills, plugins, and session control.

- [App state](https://github.com/roger2ai/claude-code-compiled/tree/main/src/state): state store · Shared app state, selectors, and context used across the UI. · `src/state`
- [Bootstrap](https://github.com/roger2ai/claude-code-compiled/tree/main/src/bootstrap): init layer · Startup setup, configuration loading, and initial state wiring. · `src/bootstrap`
- [Query loop](https://github.com/roger2ai/claude-code-compiled/blob/main/src/QueryEngine.ts): turn engine · Prompt normalization, model requests, tool calls, and message emission. · `src/QueryEngine.ts`
- [Commands](https://github.com/roger2ai/claude-code-compiled/tree/main/src/commands): slash command system · Top-level command handlers for session, config, resume, plugins, MCP, and workflows. · `src/commands`
- [Tasks](https://github.com/roger2ai/claude-code-compiled/tree/main/src/tasks): background work · Local shell tasks, remote agents, teammate tasks, and background job tracking. · `src/tasks`
- [Skills & plugins](https://github.com/roger2ai/claude-code-compiled/tree/main/src/skills): extensions · Bundled skills, plugin loading, marketplace flows, validation, and autoupdate. · `src/skills`

### Execution & Safety

Tool implementations, permissions, sandboxing, and message translation.

- [Tools](https://github.com/roger2ai/claude-code-compiled/tree/main/src/tools): tool implementations · Concrete assistant tools such as shell, file ops, search, MCP, agents, and workflows. · `src/tools`
- [Permissions](https://github.com/roger2ai/claude-code-compiled/tree/main/src/hooks/toolPermission): approval & sandbox · Tool permission hooks, approval dialogs, shell safety, allowlists, and sandbox choice. · `src/hooks/toolPermission`
- [Messages](https://github.com/roger2ai/claude-code-compiled/tree/main/src/utils/messages): message model · Message creation, mapping, rendering, and conversation timeline types. · `src/utils/messages`

### Integrations

Networked services, remote bridge/control plane, and external connectors.

- [Services](https://github.com/roger2ai/claude-code-compiled/tree/main/src/services): external services · Anthropic API, OAuth, analytics, MCP, LSP, voice, compaction, and memory services. · `src/services`
- [Bridge layer](https://github.com/roger2ai/claude-code-compiled/tree/main/src/bridge): remote control plane · IDE handoff, remote sessions, relay messaging, and process synchronization. · `src/bridge`
- [Remote control](https://github.com/roger2ai/claude-code-compiled/tree/main/src/remote): session relay · Remote session manager, websocket transport, and control-plane adapters. · `src/remote`

### Platform

Persistence, utilities, native shims, migrations, and build compatibility layers.

- [Persistence](https://github.com/roger2ai/claude-code-compiled/blob/main/src/utils/sessionStorage.ts): local durable state · Session storage, memories, settings, caches, and file persistence utilities. · `src/utils/sessionStorage.ts`
- [Core utils](https://github.com/roger2ai/claude-code-compiled/tree/main/src/utils): shared utilities · Shared helpers for shell, permissions, config, model selection, git, prompts, and CLI plumbing. · `src/utils`
- [Build shims](https://github.com/roger2ai/claude-code-compiled/tree/main/shims): compatibility · Bun and macro shims used to keep build/runtime compatibility stable. · `shims`

## Connections

- Main entry → CLI entrypoints: boots · Process startup dispatches into CLI or SDK entrypoints.
- Main entry → Bootstrap: initializes · Startup setup prepares config, auth, and session state.
- Bootstrap → App state: hydrates · Bootstrapping seeds the shared app store and context.
- CLI entrypoints → Commands: routes · CLI entrypoints dispatch command handlers.
- CLI entrypoints → Query loop: starts · Interactive modes enter the main turn engine.
- Query loop → Tools: requests tools · Model turns may emit tool calls.
- Permissions → Tools: gates · Sensitive or destructive tools are approved or blocked before execution.
- Tools → Messages: emits · Tool results are converted into conversation messages.
- Query loop → Messages: produces · Model responses and tool outputs flow into the timeline.
- Messages → UI components: renders in · Message objects are displayed by the terminal UI.
- App state → UI components: drives · UI reads state and selectors rather than point-to-point communication.
- Ink renderer → UI components: hosts · Ink provides the terminal rendering substrate for React components.
- Screens → Query loop: wraps · Full-screen modes wrap the shared interaction loop.
- Commands → App state: updates · Commands mutate session, config, and UI state.
- Commands → Tasks: controls · Command workflows can spawn or manage background tasks.
- Skills & plugins → Tools: extends · Skills and plugins contribute behavior and tool integrations.
- Skills & plugins → Commands: adds commands · Plugins can register or modify command surfaces.
- Services → Query loop: supports · API, auth, telemetry, LSP, voice, and memory services support turns and features.
- Services → Tools: backs · Several tools depend on networked service clients.
- Bridge layer → Remote control: connects · Bridge modules synchronize sessions and remote control flows.
- Bridge layer → App state: syncs · Remote control updates shared session state and permissions.
- Persistence → App state: persists · Durable local state is restored into the app store.
- Core utils → Query loop: supports · Shared helpers underpin prompting, model config, and turn execution.
- Core utils → Tools: supports · Tool execution reuses shared shell, git, fs, and validation helpers.
- Build shims → Main entry: enables build · Compatibility shims support Bun/build-time behavior.
- Build shims → Ink renderer: enables build · Renderer/runtime compatibility is stabilized by shims.
- Tasks → UI components: surfaces status · Background work feeds progress and task dialogs in the UI.
- Permissions → UI components: prompts · Permission requests are rendered as dialogs and approvals.
