winfunc/opcode

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.