# twigpine/openclaude architecture

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

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

## Overview

OpenClaude is a terminal-first coding-agent CLI that brings cloud and local model providers into one workflow. A user enters a prompt in the CLI; the query engine prepares context, processes input, streams results, and records conversation history. Around that core, the product exposes tools, agents, MCP, slash commands, provider setup, and task workflows. The graph also shows persistence and permission handling. README capabilities fill out some unsampled subsystems; arrows are limited to documented behavior and sampled calls.

Main entry points: [`src/QueryEngine.ts`](https://github.com/twigpine/openclaude/blob/main/src/QueryEngine.ts) (Query engine), [`src/Tool.ts`](https://github.com/twigpine/openclaude/blob/main/src/Tool.ts) (Agent tools), [`src/utils/plugins/pluginOptionsStorage.ts`](https://github.com/twigpine/openclaude/blob/main/src/utils/plugins/pluginOptionsStorage.ts) (Plugin system), [`src/components/ProviderManager.tsx`](https://github.com/twigpine/openclaude/blob/main/src/components/ProviderManager.tsx) (Provider setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI experience"]
  node_app["Terminal app<br/>[App.tsx]"]
  node_prompt["Prompt input<br/>[PromptInput.tsx]"]
  node_commands["Slash commands<br/>[commands.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_query["Query engine<br/>[QueryEngine.ts]"]
  node_input["Input processing"]
  node_tools["Agent tools<br/>[Tool.ts]"]
  node_agents["Worker agents<br/>[workerAgent.ts]"]
  node_permissions["Tool permissions"]
end

subgraph group_providers["Models and providers"]
  node_provider_ui["Provider setup"]
  node_model["Model services"]
end

subgraph group_extensions["Extensions and coordination"]
  node_mcp["MCP integration"]
  node_plugins["Plugin system"]
  node_bridge["Remote bridge<br/>[bridgeMain.ts]"]
  node_tasks["Task workflows<br/>[useTasksV2.ts]"]
end

subgraph group_state["Session and settings"]
  node_transcript[("Session transcripts<br/>[sessionStorage.ts]")]
  node_portable_sessions["Portable session tools"]
  node_settings[("User settings")]
  node_secure_storage[("Secure credentials")]
end

node_user(("CLI user"))
node_provider{{"Model backends"}}

node_user -->|"starts session"| node_app
node_app -->|"shows input"| node_prompt
node_prompt -->|"submits prompt"| node_query
node_query -->|"processes input"| node_input
node_query -->|"loads commands"| node_commands
node_query -->|"loads plugin cache"| node_plugins
node_query -->|"records history"| node_transcript
node_query -->|"selects model"| node_model
node_model -->|"sends requests"| node_provider
node_provider_ui -->|"updates profiles"| node_settings
node_provider_ui -->|"reads credentials"| node_secure_storage
node_input -->|"dispatches tools"| node_tools
node_tools -->|"requests approval"| node_permissions
node_tools -->|"spawns workers"| node_agents
node_tools -.->|"uses MCP tools"| node_mcp
node_plugins -->|"stores secrets"| node_secure_storage
node_plugins -->|"stores options"| node_settings
node_tasks -.->|"reads task config"| node_settings
node_portable_sessions -->|"reads session files"| node_transcript
node_user -->|"configures provider"| node_provider_ui
node_user -->|"invokes commands"| node_commands
node_bridge -.->|"manages sessions"| node_transcript

click node_app "https://github.com/twigpine/openclaude/blob/main/src/components/App.tsx"
click node_prompt "https://github.com/twigpine/openclaude/blob/main/src/components/PromptInput/PromptInput.tsx"
click node_commands "https://github.com/twigpine/openclaude/blob/main/src/commands.ts"
click node_query "https://github.com/twigpine/openclaude/blob/main/src/QueryEngine.ts"
click node_tools "https://github.com/twigpine/openclaude/blob/main/src/Tool.ts"
click node_agents "https://github.com/twigpine/openclaude/blob/main/src/coordinator/workerAgent.ts"
click node_permissions "https://github.com/twigpine/openclaude/blob/main/src/components/permissions/FilePermissionDialog/usePermissionHandler.ts"
click node_provider_ui "https://github.com/twigpine/openclaude/blob/main/src/components/ProviderManager.tsx"
click node_model "https://github.com/twigpine/openclaude/tree/main/src/services/api"
click node_mcp "https://github.com/twigpine/openclaude/tree/main/src/commands/mcp"
click node_plugins "https://github.com/twigpine/openclaude/blob/main/src/utils/plugins/pluginOptionsStorage.ts"
click node_bridge "https://github.com/twigpine/openclaude/blob/main/src/bridge/bridgeMain.ts"
click node_tasks "https://github.com/twigpine/openclaude/blob/main/src/hooks/useTasksV2.ts"
click node_transcript "https://github.com/twigpine/openclaude/blob/main/src/utils/sessionStorage.ts"
click node_portable_sessions "https://github.com/twigpine/openclaude/blob/main/src/utils/sessionStoragePortable.ts"
click node_secure_storage "https://github.com/twigpine/openclaude/blob/main/src/utils/secureStorage/macOsKeychainStorage.ts"

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_app,node_prompt,node_commands,node_user toneBlue
class node_query,node_input,node_tools,node_agents,node_permissions toneAmber
class node_provider_ui,node_model toneMint
class node_mcp,node_plugins,node_bridge,node_tasks toneRose
class node_transcript,node_portable_sessions,node_settings,node_secure_storage,node_provider toneIndigo
```

## Components

### CLI experience

- [Terminal app](https://github.com/twigpine/openclaude/blob/main/src/components/App.tsx): `src/components/App.tsx`
- [Prompt input](https://github.com/twigpine/openclaude/blob/main/src/components/PromptInput/PromptInput.tsx): `src/components/PromptInput/PromptInput.tsx`
- [Slash commands](https://github.com/twigpine/openclaude/blob/main/src/commands.ts): `src/commands.ts`

### Agent runtime

- [Query engine](https://github.com/twigpine/openclaude/blob/main/src/QueryEngine.ts): `src/QueryEngine.ts`
- **Input processing**
- [Agent tools](https://github.com/twigpine/openclaude/blob/main/src/Tool.ts): `src/Tool.ts`
- [Worker agents](https://github.com/twigpine/openclaude/blob/main/src/coordinator/workerAgent.ts): `src/coordinator/workerAgent.ts`
- [Tool permissions](https://github.com/twigpine/openclaude/blob/main/src/components/permissions/FilePermissionDialog/usePermissionHandler.ts): `src/components/permissions/FilePermissionDialog/usePermissionHandler.ts`

### Models and providers

- [Provider setup](https://github.com/twigpine/openclaude/blob/main/src/components/ProviderManager.tsx): `src/components/ProviderManager.tsx`
- [Model services](https://github.com/twigpine/openclaude/tree/main/src/services/api): `src/services/api`

### Extensions and coordination

- [MCP integration](https://github.com/twigpine/openclaude/tree/main/src/commands/mcp): `src/commands/mcp`
- [Plugin system](https://github.com/twigpine/openclaude/blob/main/src/utils/plugins/pluginOptionsStorage.ts): `src/utils/plugins/pluginOptionsStorage.ts`
- [Remote bridge](https://github.com/twigpine/openclaude/blob/main/src/bridge/bridgeMain.ts): `src/bridge/bridgeMain.ts`
- [Task workflows](https://github.com/twigpine/openclaude/blob/main/src/hooks/useTasksV2.ts): `src/hooks/useTasksV2.ts`

### Session and settings

- [Session transcripts](https://github.com/twigpine/openclaude/blob/main/src/utils/sessionStorage.ts): `src/utils/sessionStorage.ts`
- [Portable session tools](https://github.com/twigpine/openclaude/blob/main/src/utils/sessionStoragePortable.ts): `src/utils/sessionStoragePortable.ts`
- **User settings**
- [Secure credentials](https://github.com/twigpine/openclaude/blob/main/src/utils/secureStorage/macOsKeychainStorage.ts): `src/utils/secureStorage/macOsKeychainStorage.ts`

### Other components

- **CLI user**
- **Model backends**

## Connections

- CLI user → Terminal app: starts session
- Terminal app → Prompt input: shows input
- Prompt input → Query engine: submits prompt
- Query engine → Input processing: processes input
- Query engine → Slash commands: loads commands
- Query engine → Plugin system: loads plugin cache
- Query engine → Session transcripts: records history
- Query engine → Model services: selects model
- Model services → Model backends: sends requests
- Provider setup → User settings: updates profiles
- Provider setup → Secure credentials: reads credentials
- Input processing → Agent tools: dispatches tools
- Agent tools → Tool permissions: requests approval
- Agent tools → Worker agents: spawns workers
- Agent tools → MCP integration: uses MCP tools
- Plugin system → Secure credentials: stores secrets
- Plugin system → User settings: stores options
- Task workflows → User settings: reads task config
- Portable session tools → Session transcripts: reads session files
- CLI user → Provider setup: configures provider
- CLI user → Slash commands: invokes commands
- Remote bridge → Session transcripts: manages sessions