# yashusingh005/openclaude architecture

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

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

## Overview

1. **Product shape**
   OpenClaude is a terminal-first coding agent runtime, not just a chat app. The core experience is a CLI that manages prompts, tool use, agents, sessions, permissions, and streaming model output across multiple provider backends.

2. **Top-level entrypoints**
   The main runtime lives under `src/` and is launched through CLI entrypoints in `src/entrypoints`, `src/main.tsx`, and `bin/`. The repo also includes a headless gRPC server, a VS Code extension, a docs site, and a small Python helper layer for alternate provider behaviors.

3. **User interaction layer**
   The terminal UI is built around React + Ink in `src/ink`, `src/components`, `src/screens`, and `src/commands`. This layer renders the conversation, status lines, dialogs, permissions, tool progress, onboarding, and slash-command flows. It is the presentation boundary between the user and the agent runtime.

4. **Conversation and query engine**
   The central runtime loop is in `src/QueryEngine.ts` and the `src/query` / `src/utils/query*` modules. This layer turns user input into model requests, streams assistant tokens back, interprets tool calls, runs follow-up turns, enforces stop/compact/goal transitions, and maintains the conversation lifecycle.

5. **Provider and model abstraction**
   `src/integrations`, `src/services/api`, and `src/utils/provider*` form the provider routing layer. It normalizes many backends into one model interface: OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth/Codex, Ollama, Atomic Chat, Fireworks, Bedrock, Vertex, and vendor-specific gateways. Settings and auto-detection determine which endpoint, model, auth method, and usage/reporting behavior apply.

6. **Tool execution boundary**
   Tools are a major subsystem under `src/tools` and `src/services/tools`. The agent can invoke bash, file read/write/edit, grep/glob, web fetch/search, MCP tools, tasks, agents, notebook/edit operations, and specialized control tools. The runtime separates tool schema/prompting from execution, then feeds results back into the query loop.

7. **Permission and sandboxing model**
   Sensitive actions are gated through `src/hooks/toolPermission`, `src/components/permissions`, and `src/utils/permissions`. This is where bash/file/network/skill/computer-use approvals, sandbox prompts, and danger-mode controls are enforced. The architecture assumes tool calls are untrusted until explicitly approved or policy-allowed.

8. **Session, history, and persistence**
   Conversation state, transcripts, replay data, session identity, resume/fork behavior, and local storage live in `src/history.ts`, `src/state`, `src/utils/session*`, `src/services/sessionTranscript`, and `src/utils/storage`. This makes sessions recoverable and enables commands like resume, continue, export, replay, and background logs.

9. **Background, remote, and headless execution**
   There are separate execution paths for background jobs and remote/headless control. `src/cli/bg*`, `src/server`, `src/remote`, `src/grpc`, and `src/bridge` handle detached sessions, remote control, direct-connect sessions, gRPC streaming, and bridge-style integrations. These paths expose the same agent engine through different transport and lifecycle boundaries.

10. **Agent, tasks, and multi-agent orchestration**
   `src/tools/AgentTool`, `src/tasks`, `src/coordinator`, and swarm-related utilities implement subagents, teammate/worktree flows, background tasks, and coordinator/worker behavior. The architecture supports nested agent execution with model routing, permission propagation, and task-status reporting back to the main session.

11. **Extensibility layers**
   Plugins, skills, hooks, MCP, LSP, and custom commands are all first-class extension surfaces. The relevant subsystems are in `src/plugins`, `src/skills`, `src/hooks`, `src/services/mcp`, `src/services/lsp`, `src/commands`, and `src/utils/hooks`. They extend the agent without changing the core query loop, but they do participate in startup checks, discovery, trust, and policy validation.

12. **Configuration, auth, and secrets**
   Runtime behavior is driven by user settings, environment variables, secure storage, and provider profiles. `src/utils/settings`, `src/utils/secureStorage`, `src/services/oauth`, `src/utils/auth*`, and onboarding commands manage credentials and configuration. The repo explicitly separates secure secret storage from plaintext settings and supports both interactive setup and env-driven configuration.

13. **External integrations and helpers**
   The code also integrates with GitHub, search/fetch services, shell environments, IDEs, and local system capabilities such as tmux, SSH, terminal features, and optional Firecrawl/DuckDuckGo web access. The Python package provides alternate local provider helpers, while the VS Code extension packages the same ecosystem into editor workflows and launch integration.

14. **Build, docs, and delivery**
   The project is built with Bun/Node tooling, tested heavily with Bun tests, and packaged via release workflows. The `web/` Astro site is a separate docs/marketing surface, while `docs/` contains the operational guides. Architecturally, these are supporting surfaces around the same core CLI/runtime rather than separate product backends.

Main entry points: [`src/QueryEngine.ts`](https://github.com/yashusingh005/openclaude/blob/main/src/QueryEngine.ts) (Query engine), [`src/components`](https://github.com/yashusingh005/openclaude/tree/main/src/components) (Screens), [`src/main.tsx`](https://github.com/yashusingh005/openclaude/blob/main/src/main.tsx) (Main), [`src/server`](https://github.com/yashusingh005/openclaude/tree/main/src/server) (Remote paths)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI runtime"]
  node_src_entrypoints["Entrypoints"]
  node_src_main["Main<br/>app bootstrap<br/>[main.tsx]"]
  node_bin_openclaude["Bin shim<br/>launcher"]
end

subgraph group_ui["Terminal UI"]
  node_src_ink["Ink shell<br/>ui framework"]
  node_src_components["Screens<br/>ui components"]
  node_src_screens["Screen views<br/>screen routes"]
end

subgraph group_runtime["Agent runtime"]
  node_query_engine(("Query engine<br/>conversation loop<br/>[QueryEngine.ts]"))
  node_query_layer["Query helpers<br/>runtime logic"]
  node_history_state[("History<br/>session persistence<br/>[history.ts]")]
  node_tasks_area["Tasks<br/>task orchestration"]
end

subgraph group_providers["Providers"]
  node_provider_integration["Provider router<br/>model abstraction"]
  node_api_services["API services<br/>model/api layer"]
  node_provider_utils["Provider utils<br/>provider config"]
end

subgraph group_tools["Tools"]
  node_tool_catalog["Tool catalog<br/>tool definitions"]
  node_tool_exec["Tool runtime<br/>tool execution"]
  node_perm_model["Permissions<br/>approval policy"]
end

subgraph group_extensions["Extensions"]
  node_extensibility["Extensions<br/>plugin/skill/hook"]
  node_config_auth["Config & auth<br/>settings/credentials"]
end

subgraph group_remotes["Remote paths"]
  node_remote_paths["Remote paths<br/>remote/headless"]
  node_vscode_ext["VS Code ext<br/>editor extension"]
end

subgraph group_infra["Supporting surfaces"]
  node_python_helpers["Python helpers<br/>provider helpers"]
  node_docs_site["Docs site<br/>astro docs"]
end

node_src_entrypoints -->|"boots"| node_src_main
node_bin_openclaude -->|"launches"| node_src_entrypoints
node_src_main -->|"renders"| node_src_ink
node_src_main -->|"runs"| node_query_engine
node_src_ink -->|"hosts"| node_src_components
node_src_components -->|"shows"| node_perm_model
node_src_screens -->|"composes"| node_src_components
node_query_engine -->|"uses"| node_query_layer
node_query_engine -->|"invokes"| node_tool_exec
node_query_engine -->|"persists"| node_history_state
node_tool_catalog -->|"describes"| node_tool_exec
node_tool_exec -->|"gated by"| node_perm_model
node_perm_model -->|"prompts"| node_src_components
node_provider_integration -->|"routes"| node_api_services
node_api_services -->|"configures"| node_provider_utils
node_provider_utils -->|"reads"| node_config_auth
node_extensibility -->|"extends"| node_query_engine
node_extensibility -->|"managed by"| node_config_auth
node_remote_paths -->|"exposes"| node_query_engine
node_remote_paths -->|"resumes"| node_history_state
node_vscode_ext -->|"connects"| node_remote_paths
node_python_helpers -->|"adapts"| node_provider_integration
node_docs_site -.->|"documents"| node_src_entrypoints

click node_src_entrypoints "https://github.com/yashusingh005/openclaude/tree/main/src/entrypoints"
click node_src_main "https://github.com/yashusingh005/openclaude/blob/main/src/main.tsx"
click node_bin_openclaude "https://github.com/yashusingh005/openclaude/tree/main/bin/openclaude"
click node_src_ink "https://github.com/yashusingh005/openclaude/tree/main/src/ink"
click node_src_components "https://github.com/yashusingh005/openclaude/tree/main/src/components"
click node_src_screens "https://github.com/yashusingh005/openclaude/tree/main/src/screens"
click node_query_engine "https://github.com/yashusingh005/openclaude/blob/main/src/QueryEngine.ts"
click node_query_layer "https://github.com/yashusingh005/openclaude/tree/main/src/query"
click node_history_state "https://github.com/yashusingh005/openclaude/blob/main/src/history.ts"
click node_tasks_area "https://github.com/yashusingh005/openclaude/tree/main/src/tasks"
click node_provider_integration "https://github.com/yashusingh005/openclaude/tree/main/src/integrations"
click node_api_services "https://github.com/yashusingh005/openclaude/tree/main/src/services/api"
click node_provider_utils "https://github.com/yashusingh005/openclaude/blob/main/src/utils/providerDiscovery.ts"
click node_tool_catalog "https://github.com/yashusingh005/openclaude/tree/main/src/tools"
click node_tool_exec "https://github.com/yashusingh005/openclaude/tree/main/src/services/tools"
click node_perm_model "https://github.com/yashusingh005/openclaude/tree/main/src/utils/permissions"
click node_extensibility "https://github.com/yashusingh005/openclaude/tree/main/src/plugins"
click node_config_auth "https://github.com/yashusingh005/openclaude/tree/main/src/utils/settings"
click node_remote_paths "https://github.com/yashusingh005/openclaude/tree/main/src/server"
click node_vscode_ext "https://github.com/yashusingh005/openclaude/tree/main/vscode-extension/openclaude-vscode"
click node_python_helpers "https://github.com/yashusingh005/openclaude/tree/main/python"
click node_docs_site "https://github.com/yashusingh005/openclaude/tree/main/web"

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_src_entrypoints,node_src_main,node_bin_openclaude,node_remote_paths,node_vscode_ext toneBlue
class node_src_ink,node_src_components,node_src_screens,node_python_helpers,node_docs_site toneAmber
class node_query_engine,node_query_layer,node_history_state,node_tasks_area toneMint
class node_provider_integration,node_api_services,node_provider_utils toneRose
class node_tool_catalog,node_tool_exec,node_perm_model toneIndigo
class node_extensibility,node_config_auth toneTeal
```

## Components

### CLI runtime

Terminal entrypoints, REPL wiring, and command dispatch.

- [Entrypoints](https://github.com/yashusingh005/openclaude/tree/main/src/entrypoints): cli entrypoints · Primary CLI/bootstrap entrypoints for the main runtime and SDK surfaces. · `src/entrypoints`
- [Main](https://github.com/yashusingh005/openclaude/blob/main/src/main.tsx): app bootstrap · Top-level runtime bootstrapping into the terminal agent experience. · `src/main.tsx`
- [Bin shim](https://github.com/yashusingh005/openclaude/tree/main/bin/openclaude): launcher · Executable wrapper used to invoke the CLI. · `bin/openclaude`

### Terminal UI

Ink/React presentation layer for conversation and dialogs.

- [Ink shell](https://github.com/yashusingh005/openclaude/tree/main/src/ink): ui framework · Custom Ink/React terminal rendering and event system. · `src/ink`
- [Screens](https://github.com/yashusingh005/openclaude/tree/main/src/components): ui components · Conversation view, dialogs, permissions, status, and onboarding UI. · `src/components`
- [Screen views](https://github.com/yashusingh005/openclaude/tree/main/src/screens): screen routes · Top-level REPL and resume screens plus startup gating flows. · `src/screens`

### Agent runtime

Query loop, sessions, history, and task orchestration.

- [Query engine](https://github.com/yashusingh005/openclaude/blob/main/src/QueryEngine.ts): conversation loop · Turns user input into model turns, tool calls, streaming output, and turn transitions. · `src/QueryEngine.ts`
- [Query helpers](https://github.com/yashusingh005/openclaude/tree/main/src/query): runtime logic · Query configuration, stop hooks, token budgeting, and loop guards. · `src/query`
- [History](https://github.com/yashusingh005/openclaude/blob/main/src/history.ts): session persistence · Sessions, transcripts, replay, resume/fork state, and local storage. · `src/history.ts`
- [Tasks](https://github.com/yashusingh005/openclaude/tree/main/src/tasks): task orchestration · Background tasks, shells, agents, workflows, and task status models. · `src/tasks`

### Providers

Model routing, provider normalization, auth, and usage plumbing.

- [Provider router](https://github.com/yashusingh005/openclaude/tree/main/src/integrations): model abstraction · Normalizes backends, endpoints, profiles, routing, and provider metadata. · `src/integrations`
- [API services](https://github.com/yashusingh005/openclaude/tree/main/src/services/api): model/api layer · Auth, bootstrap, client, usage, shims, and provider-specific API behavior. · `src/services/api`
- [Provider utils](https://github.com/yashusingh005/openclaude/blob/main/src/utils/providerDiscovery.ts): provider config · Auto-detect, recommendation, secrets, profiles, and validation helpers. · `src/utils/providerDiscovery.ts`

### Tools

Tool schemas, execution, and permission gates.

- [Tool catalog](https://github.com/yashusingh005/openclaude/tree/main/src/tools): tool definitions · Agent-facing tool schemas and prompts for file, shell, web, task, and control operations. · `src/tools`
- [Tool runtime](https://github.com/yashusingh005/openclaude/tree/main/src/services/tools): tool execution · Streaming execution, orchestration, hooks, and result handling for tools. · `src/services/tools`
- [Permissions](https://github.com/yashusingh005/openclaude/tree/main/src/utils/permissions): approval policy · Approvals, sandboxing, dangerous-mode controls, and permission UI. · `src/utils/permissions`

### Extensions

Plugins, skills, hooks, MCP, and LSP integration.

- [Extensions](https://github.com/yashusingh005/openclaude/tree/main/src/plugins): plugin/skill/hook · Plugins, skills, hooks, MCP, and LSP extension surfaces. · `src/plugins`
- [Config & auth](https://github.com/yashusingh005/openclaude/tree/main/src/utils/settings): settings/credentials · Settings, secure storage, OAuth, and onboarding-driven configuration. · `src/utils/settings`

### Remote paths

Background, gRPC, bridge, and editor/remote entrypoints.

- [Remote paths](https://github.com/yashusingh005/openclaude/tree/main/src/server): remote/headless · Detached sessions, gRPC, bridge control, and server-side session management. · `src/server`
- [VS Code ext](https://github.com/yashusingh005/openclaude/tree/main/vscode-extension/openclaude-vscode): editor extension · Editor integration packaging a chat/session workflow around the same agent ecosystem. · `vscode-extension/openclaude-vscode`

### Supporting surfaces

Python helpers, docs site, and packaging surfaces.

- [Python helpers](https://github.com/yashusingh005/openclaude/tree/main/python): provider helpers · Alternate local provider helper layer for specific runtimes and routing behavior. · `python`
- [Docs site](https://github.com/yashusingh005/openclaude/tree/main/web): astro docs · Documentation and marketing site separate from the core CLI runtime. · `web`

## Connections

- Entrypoints → Main: boots · Entrypoints hand off to the main runtime bootstrap.
- Bin shim → Entrypoints: launches · The bin wrapper launches the CLI entrypoints.
- Main → Ink shell: renders · Main runtime mounts the terminal UI shell.
- Main → Query engine: runs · Main runtime delegates conversation handling to the query engine.
- Ink shell → Screens: hosts · Ink provides the rendering substrate for UI components.
- Screens → Permissions: shows · Permission and sandbox dialogs are rendered in the UI layer.
- Screen views → Screens: composes · Screens are assembled from the shared UI component set.
- Query engine → Query helpers: uses · The engine relies on query helpers for control-flow and limits.
- Query engine → Tool runtime: invokes · Model turns can trigger tool execution and receive results back.
- Query engine → History: persists · Conversation lifecycle state is written to session/history stores.
- Tool catalog → Tool runtime: describes · Tool definitions are executed through the tool runtime.
- Tool runtime → Permissions: gated by · Potentially sensitive tool calls go through permission checks.
- Permissions → Screens: prompts · Approval requests and sandbox decisions surface in the terminal UI.
- Provider router → API services: routes · Provider routing is implemented through API/service adapters.
- API services → Provider utils: configures · API behavior depends on discovery, profiles, secrets, and validation.
- Provider utils → Config & auth: reads · Provider choice and auth depend on settings and secret storage.
- Extensions → Query engine: extends · Plugins, skills, hooks, and MCP/LSP integrations feed into the core loop.
- Extensions → Config & auth: managed by · Extension behavior is governed by settings, trust, and onboarding state.
- Remote paths → Query engine: exposes · Headless, bridge, and server paths expose the same agent runtime.
- Remote paths → History: resumes · Remote and detached execution rely on persistent sessions and replayable state.
- VS Code ext → Remote paths: connects · The editor extension connects through the remote/session control surfaces.
- Python helpers → Provider router: adapts · Python helpers provide alternate provider behavior for specific backends.
- Docs site → Entrypoints: documents · Docs site describes CLI usage, commands, config, and providers.