How roger2ai/claude-code-compiled works
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: QueryEngine.ts Query loop · tools Tools · state App state · components UI components
Components 20
Runtime & UI
Bun entrypoints, Ink renderer, screens, components, and input handling.
- Main entry · Top-level Bun/TypeScript startup and CLI bootstrapping.
src/main.tsx - CLI entrypoints · CLI, init, MCP, and SDK entrypoints that wire process-level modes.
src/entrypoints - Ink renderer · Custom terminal rendering, layout, focus, events, and screen output.
src/ink - Screens · REPL, Doctor, and Resume Conversation screen flows.
src/screens - UI components · 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 · Shared app state, selectors, and context used across the UI.
src/state - Bootstrap · Startup setup, configuration loading, and initial state wiring.
src/bootstrap - Query loop · Prompt normalization, model requests, tool calls, and message emission.
src/QueryEngine.ts - Commands · Top-level command handlers for session, config, resume, plugins, MCP, and workflows.
src/commands - Tasks · Local shell tasks, remote agents, teammate tasks, and background job tracking.
src/tasks - Skills & plugins · Bundled skills, plugin loading, marketplace flows, validation, and autoupdate.
src/skills
Execution & Safety
Tool implementations, permissions, sandboxing, and message translation.
- Tools · Concrete assistant tools such as shell, file ops, search, MCP, agents, and workflows.
src/tools - Permissions · Tool permission hooks, approval dialogs, shell safety, allowlists, and sandbox choice.
src/hooks/toolPermission - Messages · Message creation, mapping, rendering, and conversation timeline types.
src/utils/messages
Integrations
Networked services, remote bridge/control plane, and external connectors.
- Services · Anthropic API, OAuth, analytics, MCP, LSP, voice, compaction, and memory services.
src/services - Bridge layer · IDE handoff, remote sessions, relay messaging, and process synchronization.
src/bridge - Remote control · Remote session manager, websocket transport, and control-plane adapters.
src/remote
Platform
Persistence, utilities, native shims, migrations, and build compatibility layers.
- Persistence · Session storage, memories, settings, caches, and file persistence utilities.
src/utils/sessionStorage.ts - Core utils · Shared helpers for shell, permissions, config, model selection, git, prompts, and CLI plumbing.
src/utils - Build shims · Bun and macro shims used to keep build/runtime compatibility stable.
shims
Connections 28
- 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.