How ambujaak/openclaude works
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: main.tsx Main app · tools Tool suite · api Provider API · QueryEngine.ts Query engine
Components 23
CLI runtime
Terminal-first entrypoints, app composition, and interactive control flow.
- CLI entrypoint · Starts the terminal app and composes the main runtime.
src/entrypoints/cli.tsx - Main app · Assembles config, state, providers, and interactive flow.
src/main.tsx - Slash commands · User-facing command facade over deeper runtime services.
src/commands
Terminal UI
Ink-style rendering, React components, dialogs, and prompt surfaces.
Agent core
Conversation loop, tasks, tool orchestration, and model requests.
- Query engine · Coordinates prompt submission, model calls, tool use, and iteration.
src/QueryEngine.ts - Task model · Represents foreground, background, teammate, shell, and remote tasks.
src/Task.ts - Tool suite · Bash, file, search, MCP, tasks, skills, and other agent tools.
src/tools - Tool execution · Runs tools, streams results, and applies orchestration hooks.
src/services/tools
Models & providers
Provider abstraction, request routing, streaming clients, and discovery.
- Provider API · Provider configuration, validation, and request/response routing.
src/services/api - Model utils · Model discovery, aliases, recommendations, and compatibility checks.
src/utils/model - Streaming IO · Structured and remote IO plus streaming transports.
src/cli/transports
Sessions & runtime
Session state, background work, remote control, bridge, and REPL wiring.
- Session state · App state, selectors, and session-oriented client state.
src/state - Session services · History, resume, compact, summaries, and background task coordination.
src/services - Bridge & remote · Session bridge, remote messaging, trusted devices, and REPL session wiring.
src/bridge
Extensions
MCP, plugins, skills, and external environment integrations.
- Extensibility · MCP servers, plugins, skills, and related loading and UI.
src/services/mcp - Integrations · IDE, shell, GitHub, OAuth, voice, deep links, and managed settings.
src/services/github - VS Code extension · Optional extension package for IDE integration.
vscode-extension/openclaude-vscode
Support systems
Permissions, persistence, telemetry, maintenance scripts, and auxiliary language support.
- Permissions · Tool permissions, trust dialogs, sandboxing, and managed settings.
src/utils/permissions - Local storage · Session storage, memory, secure storage, caches, and file persistence.
src/utils - Telemetry · Analytics, event logging, instrumentation, and export sinks.
src/services/analytics - Maintenance scripts · Build, provider bootstrap/discovery, system checks, and privacy verification.
scripts - Python helper · Small provider/router helpers used for testing and auxiliary workflows.
python
Connections 27
- 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.