# ambujaak/openclaude architecture

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

- Interactive diagram: https://gitdiagram.com/ambujaak/openclaude
- Repository: https://github.com/ambujaak/openclaude

## Overview

1. **Top-level shape**
   OpenClaude is a Bun/TypeScript terminal-first coding agent CLI. The core product lives in `src/`, with supporting automation in `scripts/`, a small Python helper layer in `python/`, and an optional VS Code extension in `vscode-extension/openclaude-vscode/`.

2. **CLI entry and runtime composition**
   The runtime starts from `src/entrypoints/cli.tsx` and `src/main.tsx`, then assembles the app from configuration, provider selection, keybindings, state stores, and UI. The CLI is not a thin wrapper: it hosts the interactive agent loop, command dispatcher, tool execution, and background services inside one process.

3. **Terminal UI shell**
   The interactive experience is built on a custom Ink-like terminal UI layer in `src/ink/` plus app-level React components in `src/components/`. This layer renders prompts, message streams, dialogs, status lines, and command palettes, and it is the primary boundary between user input and the agent/runtime.

4. **Conversation and agent loop**
   Core agent orchestration is centered around `src/QueryEngine.ts`, `src/Task.ts`, `src/tools/`, `src/services/tools/`, and `src/utils/handlePromptSubmit.ts`. User prompts flow into a query/session loop, which chooses tools, sends model requests, receives streaming tokens, and iterates through tool calls until completion.

5. **Tool execution subsystem**
   Tools are a major architectural unit: bash, file read/write/edit, grep/glob, web search/fetch, MCP, tasks, agents, notebook edits, and more live under `src/tools/`. Each tool has UI, prompt/schema, and execution logic. Tool execution is mediated by `src/services/tools/` and permission checks in `src/hooks/toolPermission/` plus `src/components/permissions/`.

6. **Provider and model abstraction**
   Model access is provider-agnostic. Provider config, discovery, recommendation, and validation live under `src/services/api/`, `src/utils/model/`, `src/utils/provider*`, and related command handlers like `/provider`. The repo supports OpenAI-compatible APIs, Gemini, GitHub Models, Codex, Ollama, Atomic Chat, Bedrock, and others through a shared request/response contract and routing layer.

7. **Streaming IO and transport boundaries**
   Streaming output is handled explicitly through CLI transport modules in `src/cli/transports/` and I/O helpers in `src/cli/remoteIO.ts`, `src/cli/structuredIO.ts`, and `src/services/api/client.ts`. This boundary separates model/event streaming from presentation, allowing both interactive terminal updates and noninteractive/structured consumers.

8. **Commands and slash-command surface**
   User-facing behavior is mostly exposed as slash commands in `src/commands/`. These command modules provide the control surface for provider setup, sessions, agents, permissions, MCP, logs, review, resume, config, and operational flows. The command layer is a routing facade over the deeper runtime services.

9. **Session, tasks, and background work**
   Session state and task lifecycles are modeled separately from the UI. `src/state/`, `src/tasks/`, `src/services/session*`, `src/services/compact/`, `src/services/autoDream/`, and `src/services/awaySummary.ts` manage persistence, resumption, compaction, background tasks, summaries, and “teammate”/multi-agent execution. This is where foreground conversation, background jobs, and resumed sessions converge.

10. **Remote control, bridge, and repl/session wiring**
   The `src/bridge/`, `src/remote/`, `src/server/`, `src/replLauncher.tsx`, and related session manager files implement remote control and bridge-style communication. These modules handle session creation, authenticated messaging, trusted-device/work-secret logic, and transport between local CLI state and remote or attached clients.

11. **Extensions around MCP, plugins, and skills**
   OpenClaude is extensible in several orthogonal ways: MCP integration (`src/services/mcp/`, `src/components/mcp/`, `src/tools/MCPTool/`), plugins (`src/services/plugins/`, `src/utils/plugins/`, `src/commands/plugin/`), and skills (`src/skills/`, `src/tools/SkillTool/`, `src/utils/skills/`). These are loaded, validated, surfaced in UI, and then folded into the tool/agent runtime.

12. **Environment integrations**
   The repo includes first-class integrations for IDEs, terminals, shells, GitHub, OAuth, web search/fetch, voice, and remote environments. Key modules include `src/services/github/`, `src/services/oauth/`, `src/services/lsp/`, `src/utils/ide.ts`, `src/utils/shell/`, `src/utils/deepLink/`, `src/services/voice.ts`, and `src/services/remoteManagedSettings/`. These integrations mostly attach to the same core loop through specialized tools, hooks, and settings.

13. **Security, permissions, and policy**
   Permissions are not an afterthought; they are a dedicated subsystem spanning `src/utils/permissions/`, `src/components/permissions/`, `src/hooks/toolPermission/`, and tool-specific safety code such as bash and PowerShell validators. This layer gates file, shell, network, and plan-mode actions, and also supports managed settings, trust dialogs, sandboxing, and no-phone-home verification.

14. **Persistence, telemetry, and maintenance**
   Local persistence covers sessions, history, memory, caches, and secure storage (`src/utils/sessionStorage*`, `src/memdir/`, `src/utils/secureStorage/`, `src/utils/cachePaths.ts`). Telemetry and analytics are isolated under `src/services/analytics/` and `src/utils/telemetry/`, while repo-level scripts in `scripts/` handle build, runtime checks, privacy verification, and coverage reporting. The Python package mirrors a small provider/router slice for testing and auxiliary workflows, not the primary CLI runtime.

Main entry points: [`src/main.tsx`](https://github.com/ambujaak/openclaude/blob/main/src/main.tsx) (Main app), [`src/tools`](https://github.com/ambujaak/openclaude/tree/main/src/tools) (Tool suite), [`src/services/api`](https://github.com/ambujaak/openclaude/tree/main/src/services/api) (Provider API), [`src/QueryEngine.ts`](https://github.com/ambujaak/openclaude/blob/main/src/QueryEngine.ts) (Query engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_entrypoints["CLI entrypoint<br/>bun/tsx entry<br/>[cli.tsx]"]
  node_main["Main app<br/>app bootstrap<br/>[main.tsx]"]
  node_commands["Slash commands<br/>command routing"]
end

subgraph group_ui["Terminal UI"]
  node_ink["Ink layer<br/>terminal renderer"]
  node_components["App UI<br/>react components"]
end

subgraph group_agent["Agent core"]
  node_queryengine["Query engine<br/>agent loop<br/>[QueryEngine.ts]"]
  node_task["Task model<br/>task orchestration<br/>[Task.ts]"]
  node_tools["Tool suite<br/>tool implementations"]
  node_toolsvc["Tool execution<br/>execution services"]
end

subgraph group_providers["Models & providers"]
  node_providerapi["Provider API<br/>model routing"]
  node_modelutils["Model utils<br/>provider helpers"]
  node_cliio["Streaming IO<br/>transport boundary"]
end

subgraph group_runtime["Sessions & runtime"]
  node_state["Session state<br/>persistence/state"]
  node_sessions["Session services<br/>session lifecycle"]
  node_bridge["Bridge & remote<br/>remote control"]
end

subgraph group_ext["Extensions"]
  node_mcpplugins["Extensibility<br/>mcp/plugins/skills"]
  node_integrations["Integrations"]
  node_vscode["VS Code extension<br/>editor extension"]
end

subgraph group_ops["Support systems"]
  node_security["Permissions<br/>policy gate"]
  node_persistence["Local storage<br/>storage/cache"]
  node_telemetry["Telemetry<br/>analytics/logging"]
  node_scripts["Maintenance scripts<br/>build/ops scripts"]
  node_python["Python helper<br/>auxiliary provider layer"]
end

node_entrypoints -->|"bootstraps"| node_main
node_main -->|"renders in"| node_ink
node_main -->|"composes"| node_components
node_main -->|"drives"| node_queryengine
node_main -->|"loads"| node_state
node_main -->|"dispatches"| node_commands
node_queryengine -->|"selects tools"| node_tools
node_queryengine -->|"executes via"| node_toolsvc
node_queryengine -->|"requests models"| node_providerapi
node_toolsvc -->|"checks policy"| node_security
node_tools -->|"request approval"| node_security
node_tools -->|"read/write"| node_persistence
node_providerapi -->|"resolves"| node_modelutils
node_providerapi -->|"streams through"| node_cliio
node_state -->|"stores"| node_sessions
node_sessions -->|"coordinates"| node_bridge
node_bridge -->|"transports"| node_cliio
node_commands -->|"operates on"| node_sessions
node_commands -->|"manages"| node_mcpplugins
node_mcpplugins -->|"extends"| node_tools
node_integrations -->|"feeds"| node_tools
node_integrations -->|"surface"| node_commands
node_python -.->|"mirrors"| node_providerapi
node_scripts -->|"supports"| node_providerapi
node_scripts -->|"verifies"| node_telemetry
node_telemetry -->|"observes"| node_main
node_vscode -.->|"augments"| node_integrations

click node_entrypoints "https://github.com/ambujaak/openclaude/blob/main/src/entrypoints/cli.tsx"
click node_main "https://github.com/ambujaak/openclaude/blob/main/src/main.tsx"
click node_ink "https://github.com/ambujaak/openclaude/tree/main/src/ink"
click node_components "https://github.com/ambujaak/openclaude/tree/main/src/components"
click node_queryengine "https://github.com/ambujaak/openclaude/blob/main/src/QueryEngine.ts"
click node_task "https://github.com/ambujaak/openclaude/blob/main/src/Task.ts"
click node_tools "https://github.com/ambujaak/openclaude/tree/main/src/tools"
click node_toolsvc "https://github.com/ambujaak/openclaude/tree/main/src/services/tools"
click node_providerapi "https://github.com/ambujaak/openclaude/tree/main/src/services/api"
click node_modelutils "https://github.com/ambujaak/openclaude/tree/main/src/utils/model"
click node_cliio "https://github.com/ambujaak/openclaude/tree/main/src/cli/transports"
click node_state "https://github.com/ambujaak/openclaude/tree/main/src/state"
click node_sessions "https://github.com/ambujaak/openclaude/tree/main/src/services"
click node_bridge "https://github.com/ambujaak/openclaude/tree/main/src/bridge"
click node_commands "https://github.com/ambujaak/openclaude/tree/main/src/commands"
click node_mcpplugins "https://github.com/ambujaak/openclaude/tree/main/src/services/mcp"
click node_integrations "https://github.com/ambujaak/openclaude/tree/main/src/services/github"
click node_security "https://github.com/ambujaak/openclaude/tree/main/src/utils/permissions"
click node_persistence "https://github.com/ambujaak/openclaude/tree/main/src/utils"
click node_telemetry "https://github.com/ambujaak/openclaude/tree/main/src/services/analytics"
click node_scripts "https://github.com/ambujaak/openclaude/tree/main/scripts"
click node_python "https://github.com/ambujaak/openclaude/tree/main/python"
click node_vscode "https://github.com/ambujaak/openclaude/tree/main/vscode-extension/openclaude-vscode"

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_entrypoints,node_main,node_commands,node_security,node_persistence,node_telemetry,node_scripts,node_python toneBlue
class node_ink,node_components toneAmber
class node_queryengine,node_task,node_tools,node_toolsvc toneMint
class node_providerapi,node_modelutils,node_cliio toneRose
class node_state,node_sessions,node_bridge toneIndigo
class node_mcpplugins,node_integrations,node_vscode toneTeal
```

## Components

### CLI runtime

Terminal-first entrypoints, app composition, and interactive control flow.

- [CLI entrypoint](https://github.com/ambujaak/openclaude/blob/main/src/entrypoints/cli.tsx): bun/tsx entry · Starts the terminal app and composes the main runtime. · `src/entrypoints/cli.tsx`
- [Main app](https://github.com/ambujaak/openclaude/blob/main/src/main.tsx): app bootstrap · Assembles config, state, providers, and interactive flow. · `src/main.tsx`
- [Slash commands](https://github.com/ambujaak/openclaude/tree/main/src/commands): command routing · User-facing command facade over deeper runtime services. · `src/commands`

### Terminal UI

Ink-style rendering, React components, dialogs, and prompt surfaces.

- [Ink layer](https://github.com/ambujaak/openclaude/tree/main/src/ink): terminal renderer · Custom terminal rendering, events, layout, and screen management. · `src/ink`
- [App UI](https://github.com/ambujaak/openclaude/tree/main/src/components): react components · Prompt, messages, dialogs, status, and command surfaces. · `src/components`

### Agent core

Conversation loop, tasks, tool orchestration, and model requests.

- [Query engine](https://github.com/ambujaak/openclaude/blob/main/src/QueryEngine.ts): agent loop · Coordinates prompt submission, model calls, tool use, and iteration. · `src/QueryEngine.ts`
- [Task model](https://github.com/ambujaak/openclaude/blob/main/src/Task.ts): task orchestration · Represents foreground, background, teammate, shell, and remote tasks. · `src/Task.ts`
- [Tool suite](https://github.com/ambujaak/openclaude/tree/main/src/tools): tool implementations · Bash, file, search, MCP, tasks, skills, and other agent tools. · `src/tools`
- [Tool execution](https://github.com/ambujaak/openclaude/tree/main/src/services/tools): execution services · Runs tools, streams results, and applies orchestration hooks. · `src/services/tools`

### Models & providers

Provider abstraction, request routing, streaming clients, and discovery.

- [Provider API](https://github.com/ambujaak/openclaude/tree/main/src/services/api): model routing · Provider configuration, validation, and request/response routing. · `src/services/api`
- [Model utils](https://github.com/ambujaak/openclaude/tree/main/src/utils/model): provider helpers · Model discovery, aliases, recommendations, and compatibility checks. · `src/utils/model`
- [Streaming IO](https://github.com/ambujaak/openclaude/tree/main/src/cli/transports): transport boundary · Structured and remote IO plus streaming transports. · `src/cli/transports`

### Sessions & runtime

Session state, background work, remote control, bridge, and REPL wiring.

- [Session state](https://github.com/ambujaak/openclaude/tree/main/src/state): persistence/state · App state, selectors, and session-oriented client state. · `src/state`
- [Session services](https://github.com/ambujaak/openclaude/tree/main/src/services): session lifecycle · History, resume, compact, summaries, and background task coordination. · `src/services`
- [Bridge & remote](https://github.com/ambujaak/openclaude/tree/main/src/bridge): remote control · Session bridge, remote messaging, trusted devices, and REPL session wiring. · `src/bridge`

### Extensions

MCP, plugins, skills, and external environment integrations.

- [Extensibility](https://github.com/ambujaak/openclaude/tree/main/src/services/mcp): mcp/plugins/skills · MCP servers, plugins, skills, and related loading and UI. · `src/services/mcp`
- [Integrations](https://github.com/ambujaak/openclaude/tree/main/src/services/github): external integrations · IDE, shell, GitHub, OAuth, voice, deep links, and managed settings. · `src/services/github`
- [VS Code extension](https://github.com/ambujaak/openclaude/tree/main/vscode-extension/openclaude-vscode): editor extension · Optional extension package for IDE integration. · `vscode-extension/openclaude-vscode`

### Support systems

Permissions, persistence, telemetry, maintenance scripts, and auxiliary language support.

- [Permissions](https://github.com/ambujaak/openclaude/tree/main/src/utils/permissions): policy gate · Tool permissions, trust dialogs, sandboxing, and managed settings. · `src/utils/permissions`
- [Local storage](https://github.com/ambujaak/openclaude/tree/main/src/utils): storage/cache · Session storage, memory, secure storage, caches, and file persistence. · `src/utils`
- [Telemetry](https://github.com/ambujaak/openclaude/tree/main/src/services/analytics): analytics/logging · Analytics, event logging, instrumentation, and export sinks. · `src/services/analytics`
- [Maintenance scripts](https://github.com/ambujaak/openclaude/tree/main/scripts): build/ops scripts · Build, provider bootstrap/discovery, system checks, and privacy verification. · `scripts`
- [Python helper](https://github.com/ambujaak/openclaude/tree/main/python): auxiliary provider layer · Small provider/router helpers used for testing and auxiliary workflows. · `python`

## Connections

- CLI entrypoint → Main app: bootstraps · CLI startup hands control to the main app composition.
- Main app → Ink layer: renders in · Main app mounts the terminal UI layer.
- Main app → App UI: composes · Main app uses React components for interactive surfaces.
- Main app → Query engine: drives · Main app routes prompts into the agent loop.
- Main app → Session state: loads · Main app initializes shared app/session state.
- Main app → Slash commands: dispatches · Slash commands are wired into the runtime.
- Query engine → Tool suite: selects tools · Agent loop chooses tools to satisfy tasks.
- Query engine → Tool execution: executes via · Tool calls are mediated through execution services.
- Query engine → Provider API: requests models · Model messages and streaming responses flow through provider routing.
- Tool execution → Permissions: checks policy · Tool execution is gated by permissions and trust rules.
- Tool suite → Permissions: request approval · Tool implementations surface permissions and safety checks.
- Tool suite → Local storage: read/write · Tools operate on files, caches, sessions, and local artifacts.
- Provider API → Model utils: resolves · Provider routing relies on discovery and model validation helpers.
- Provider API → Streaming IO: streams through · Model events are transported via structured and streaming IO.
- Session state → Session services: stores · State is backed by session, history, and background work services.
- Session services → Bridge & remote: coordinates · Background, remote, and resumed sessions cross the bridge boundary.
- Bridge & remote → Streaming IO: transports · Remote and REPL wiring use explicit transport modules.
- Slash commands → Session services: operates on · Commands manipulate session, resume, compact, and background flows.
- Slash commands → Extensibility: manages · Commands expose MCP, plugin, and skill administration.
- Extensibility → Tool suite: extends · Extensibility packages are folded into the agent tool surface.
- Integrations → Tool suite: feeds · IDE, shell, GitHub, OAuth, and voice integrations connect through tools and hooks.
- Integrations → Slash commands: surface · Several integrations are exposed through command workflows.
- Python helper → Provider API: mirrors · Python helpers mirror a small provider/router slice.
- Maintenance scripts → Provider API: supports · Scripts handle bootstrap, discovery, recommendation, and checks.
- Maintenance scripts → Telemetry: verifies · Maintenance scripts include privacy and no-phone-home checks.
- Telemetry → Main app: observes · Runtime telemetry and logging are attached to the app process.
- VS Code extension → Integrations: augments · The optional extension provides IDE-side integration.
