# winfunc/opcode architecture

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

- Interactive diagram: https://gitdiagram.com/winfunc/opcode
- Repository: https://github.com/winfunc/opcode

## Overview

#### Purpose and Runtime
opcode is a local-first desktop GUI/toolkit for the Claude Code CLI: it manages Claude projects and interactive sessions, custom background agents, MCP configuration, usage data, and session checkpoints. It runs a React/TypeScript Vite frontend inside a Tauri 2 webview backed by Rust; SQLite is the stated local database. Claude Code is an external executable dependency. Entry points are `src/main.tsx`, `src/App.tsx`, `src-tauri/src/main.rs`, and `src-tauri/src/lib.rs`.

#### Desktop Boundary and Command API
The Tauri backend owns privileged local-machine operations—filesystem access, persistence, subprocesses, and configuration—and exposes them as command domains to the frontend. Core command modules are `src-tauri/src/commands/mod.rs`, `src-tauri/src/commands/claude.rs`, `src-tauri/src/commands/agents.rs`, `src-tauri/src/commands/mcp.rs`, and `src-tauri/src/commands/storage.rs`. Tauri permissions/capabilities are defined at `src-tauri/capabilities/default.json`; application packaging/runtime configuration is `src-tauri/tauri.conf.json`.

#### Claude Session Lifecycle
The central user flow is project selection → historical session browsing or new/resumed Claude session → streamed output and controls. Frontend session orchestration is centered on `src/components/ClaudeCodeSession.tsx`, its decomposed view pieces under `src/components/claude-code-session/`, and `src/components/SessionOutputViewer.tsx`. Rust locates/invokes the installed CLI through `src-tauri/src/claude_binary.rs` and Claude command handlers. The boundary is explicit: UI renders state and sends commands; Rust launches/manages the CLI and accesses local Claude data.

#### Process Isolation and Agents
Custom agents are configured, launched, and tracked separately from interactive sessions, preserving non-blocking background execution. UI surfaces include `src/components/CCAgents.tsx`, `src/components/AgentExecution.tsx`, and `src/components/AgentRunsList.tsx`; backend control is `src-tauri/src/commands/agents.rs` plus `src-tauri/src/process/registry.rs`. Included agent definitions in `cc_agents/*.opcode.json` provide shipped examples/templates. Agent permissions and subprocess lifecycle are architecturally security-sensitive.

#### State, Navigation, and Local Persistence
The React layer uses stores for session/agent state and contexts for tabbed workspace and theming: `src/stores/sessionStore.ts`, `src/stores/agentStore.ts`, and `src/contexts/TabContext.tsx`. Persistence adapters retain session/tab UI continuity via `src/services/sessionPersistence.ts` and `src/services/tabPersistence.ts`; durable backend storage is mediated by `src-tauri/src/commands/storage.rs`. This separates transient UI state from desktop-owned persisted data.

#### Checkpoints and Timeline Branching
Checkpointing provides session versioning, restore, fork, and timeline navigation. The backend subsystem divides orchestration, state representation, and storage among `src-tauri/src/checkpoint/manager.rs`, `src-tauri/src/checkpoint/state.rs`, and `src-tauri/src/checkpoint/storage.rs`. The frontend integrates it through `src/components/claude-code-session/useCheckpoints.ts` and `src/components/TimelineNavigator.tsx`, making checkpoint operations part of the active session workflow rather than a standalone feature.

#### Configuration and Supporting Integrations
MCP servers, slash commands, proxy settings, and usage reporting are separate command/UI domains. Relevant boundaries are `src-tauri/src/commands/mcp.rs` with `src/components/MCPManager.tsx`; `src-tauri/src/commands/slash_commands.rs`; `src-tauri/src/commands/proxy.rs`; and `src-tauri/src/commands/usage.rs` with `src/components/UsageDashboard.tsx`. The repository also has a web-serving path (`src-tauri/src/web_server.rs`, `src-tauri/src/web_main.rs`), suggesting an alternate or embedded local-web execution mode alongside the primary Tauri desktop runtime.

Main entry points: [`src-tauri/src/commands/mod.rs`](https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/mod.rs) (Command API), [`src/App.tsx`](https://github.com/winfunc/opcode/blob/main/src/App.tsx) (App shell), [`src-tauri/src/commands/storage.rs`](https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/storage.rs) (Storage commands), [`src/components/ClaudeCodeSession.tsx`](https://github.com/winfunc/opcode/blob/main/src/components/ClaudeCodeSession.tsx) (Session workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_web_entry["Web entry<br/>React entry<br/>[main.tsx]"]
  node_app["App shell<br/>React app<br/>[App.tsx]"]
  node_workspace_state["Workspace state<br/>stores &amp; context<br/>[sessionStore.ts]"]
  node_session_ui["Session workspace<br/>session UI"]
  node_checkpoint_ui["Checkpoint UI<br/>session feature<br/>[useCheckpoints.ts]"]
  node_agent_ui["Agent workspace<br/>agent UI<br/>[CCAgents.tsx]"]
  node_integration_ui["Integration dashboards<br/>MCP &amp; usage UI<br/>[MCPManager.tsx]"]
  node_ui_persistence["UI persistence<br/>persistence adapters"]
end

subgraph group_backend["Tauri backend"]
  node_tauri_entry{{"Tauri runtime<br/>Rust entry<br/>[main.rs]"}}
  node_command_api["Command API<br/>Tauri commands<br/>[mod.rs]"]
  node_claude_commands["Claude commands<br/>command domain<br/>[claude.rs]"]
  node_agent_commands["Agent commands<br/>command domain<br/>[agents.rs]"]
  node_config_commands["Integration commands<br/>command domains<br/>[mcp.rs]"]
  node_storage_commands["Storage commands<br/>command domain<br/>[storage.rs]"]
  node_checkpoint_manager["Checkpoint manager<br/>checkpoint orchestration<br/>[manager.rs]"]
  node_process_registry["Process registry<br/>subprocess lifecycle<br/>[registry.rs]"]
  node_web_mode["Local web mode<br/>alternate runtime<br/>[web_main.rs]"]
end

subgraph group_local["Local services"]
  node_claude_cli{{"Claude Code CLI<br/>external executable"}}
  node_local_database[("SQLite database<br/>local database")]
end

node_web_entry -->|"mounts"| node_app
node_app -->|"uses"| node_workspace_state
node_app -->|"hosts"| node_session_ui
node_app -->|"hosts"| node_agent_ui
node_app -->|"hosts"| node_integration_ui
node_session_ui -->|"includes"| node_checkpoint_ui
node_session_ui -->|"invokes"| node_command_api
node_agent_ui -->|"invokes"| node_command_api
node_integration_ui -->|"invokes"| node_command_api
node_workspace_state -->|"persists continuity"| node_ui_persistence
node_ui_persistence -->|"uses durable storage"| node_storage_commands
node_tauri_entry -->|"exposes"| node_command_api
node_command_api -->|"routes"| node_claude_commands
node_command_api -->|"routes"| node_agent_commands
node_command_api -->|"routes"| node_config_commands
node_command_api -->|"routes"| node_storage_commands
node_claude_commands -->|"locates and launches"| node_claude_cli
node_agent_commands -->|"manages"| node_process_registry
node_checkpoint_ui -->|"operates"| node_checkpoint_manager
node_checkpoint_manager -->|"stores checkpoints"| node_storage_commands
node_storage_commands -->|"reads and writes"| node_local_database
node_web_mode -.->|"uses"| node_command_api

click node_web_entry "https://github.com/winfunc/opcode/blob/main/src/main.tsx"
click node_app "https://github.com/winfunc/opcode/blob/main/src/App.tsx"
click node_workspace_state "https://github.com/winfunc/opcode/blob/main/src/stores/sessionStore.ts"
click node_session_ui "https://github.com/winfunc/opcode/blob/main/src/components/ClaudeCodeSession.tsx"
click node_checkpoint_ui "https://github.com/winfunc/opcode/blob/main/src/components/claude-code-session/useCheckpoints.ts"
click node_agent_ui "https://github.com/winfunc/opcode/blob/main/src/components/CCAgents.tsx"
click node_integration_ui "https://github.com/winfunc/opcode/blob/main/src/components/MCPManager.tsx"
click node_ui_persistence "https://github.com/winfunc/opcode/blob/main/src/services/sessionPersistence.ts"
click node_tauri_entry "https://github.com/winfunc/opcode/blob/main/src-tauri/src/main.rs"
click node_command_api "https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/mod.rs"
click node_claude_commands "https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/claude.rs"
click node_agent_commands "https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/agents.rs"
click node_config_commands "https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/mcp.rs"
click node_storage_commands "https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/storage.rs"
click node_checkpoint_manager "https://github.com/winfunc/opcode/blob/main/src-tauri/src/checkpoint/manager.rs"
click node_process_registry "https://github.com/winfunc/opcode/blob/main/src-tauri/src/process/registry.rs"
click node_web_mode "https://github.com/winfunc/opcode/blob/main/src-tauri/src/web_main.rs"

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_web_entry,node_app,node_workspace_state,node_session_ui,node_checkpoint_ui,node_agent_ui,node_integration_ui,node_ui_persistence toneBlue
class node_tauri_entry,node_command_api,node_claude_commands,node_agent_commands,node_config_commands,node_storage_commands,node_checkpoint_manager,node_process_registry,node_web_mode toneAmber
class node_claude_cli,node_local_database toneMint
```

## Components

### React frontend

Vite UI running in the Tauri webview.

- [Web entry](https://github.com/winfunc/opcode/blob/main/src/main.tsx): React entry · `src/main.tsx`
- [App shell](https://github.com/winfunc/opcode/blob/main/src/App.tsx): React app · `src/App.tsx`
- [Workspace state](https://github.com/winfunc/opcode/blob/main/src/stores/sessionStore.ts): stores & context · Session, agent, tab, and theme state. · `src/stores/sessionStore.ts`
- [Session workspace](https://github.com/winfunc/opcode/blob/main/src/components/ClaudeCodeSession.tsx): session UI · Drives session controls and streamed output. · `src/components/ClaudeCodeSession.tsx`
- [Checkpoint UI](https://github.com/winfunc/opcode/blob/main/src/components/claude-code-session/useCheckpoints.ts): session feature · Timeline, restore, and fork controls. · `src/components/claude-code-session/useCheckpoints.ts`
- [Agent workspace](https://github.com/winfunc/opcode/blob/main/src/components/CCAgents.tsx): agent UI · Configures and monitors background agent runs. · `src/components/CCAgents.tsx`
- [Integration dashboards](https://github.com/winfunc/opcode/blob/main/src/components/MCPManager.tsx): MCP & usage UI · `src/components/MCPManager.tsx`
- [UI persistence](https://github.com/winfunc/opcode/blob/main/src/services/sessionPersistence.ts): persistence adapters · Retains session and tab continuity. · `src/services/sessionPersistence.ts`

### Tauri backend

Privileged local-machine command and lifecycle layer.

- [Tauri runtime](https://github.com/winfunc/opcode/blob/main/src-tauri/src/main.rs): Rust entry · Registers the desktop application and command API. · `src-tauri/src/main.rs`
- [Command API](https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/mod.rs): Tauri commands · Frontend boundary for privileged operations. · `src-tauri/src/commands/mod.rs`
- [Claude commands](https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/claude.rs): command domain · Creates, resumes, and controls CLI sessions. · `src-tauri/src/commands/claude.rs`
- [Agent commands](https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/agents.rs): command domain · Launches and tracks isolated background agents. · `src-tauri/src/commands/agents.rs`
- [Integration commands](https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/mcp.rs): command domains · MCP, slash-command, proxy, and usage operations. · `src-tauri/src/commands/mcp.rs`
- [Storage commands](https://github.com/winfunc/opcode/blob/main/src-tauri/src/commands/storage.rs): command domain · Mediates durable desktop data. · `src-tauri/src/commands/storage.rs`
- [Checkpoint manager](https://github.com/winfunc/opcode/blob/main/src-tauri/src/checkpoint/manager.rs): checkpoint orchestration · Coordinates checkpoint state, restore, and forks. · `src-tauri/src/checkpoint/manager.rs`
- [Process registry](https://github.com/winfunc/opcode/blob/main/src-tauri/src/process/registry.rs): subprocess lifecycle · Tracks running agent processes. · `src-tauri/src/process/registry.rs`
- [Local web mode](https://github.com/winfunc/opcode/blob/main/src-tauri/src/web_main.rs): alternate runtime · Embedded or alternate local-web execution path. · `src-tauri/src/web_main.rs`

### Local services

Desktop-owned persistence and external local dependencies.

- **Claude Code CLI**: external executable · Installed local dependency invoked by Rust.
- **SQLite database**: local database · Durable application and checkpoint data.

## Connections

- Web entry → App shell: mounts
- App shell → Workspace state: uses
- App shell → Session workspace: hosts
- App shell → Agent workspace: hosts
- App shell → Integration dashboards: hosts
- Session workspace → Checkpoint UI: includes
- Session workspace → Command API: invokes
- Agent workspace → Command API: invokes
- Integration dashboards → Command API: invokes
- Workspace state → UI persistence: persists continuity
- UI persistence → Storage commands: uses durable storage
- Tauri runtime → Command API: exposes
- Command API → Claude commands: routes
- Command API → Agent commands: routes
- Command API → Integration commands: routes
- Command API → Storage commands: routes
- Claude commands → Claude Code CLI: locates and launches
- Agent commands → Process registry: manages
- Checkpoint UI → Checkpoint manager: operates
- Checkpoint manager → Storage commands: stores checkpoints
- Storage commands → SQLite database: reads and writes
- Local web mode → Command API: uses