Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Opcode is a powerful desktop application and toolkit built to provide a graphical interface for Claude Code. The system is architected using a dual-layered approach: a high-performance Rust backend powered by Tauri 2 and a modern React frontend. It bridges the gap between the command-line interface of Claude Code and a visual development environment, supporting both desktop native execution and a web server mode for mobile/browser access.
The project emphasizes process isolation, local-first data storage via SQLite, and real-time streaming of AI responses. It serves as a command center for managing interactive sessions, custom AI agents, and Model Context Protocol (MCP) servers.
Sources: README.md:27-33, web_server.design.md:5-15, package.json:34-70
System Component Model
The application follows a standard Tauri architecture where the frontend (UI) communicates with the backend (Core) via an asynchronous IPC (Inter-Process Communication) bridge.
The diagram shows the interaction between the React frontend, the Rust backend, and the external Claude binary execution.
Sources: README.md:244-256, web_server.design.md:12-20, src/lib/apiAdapter.ts:133-145
Frontend Architecture
The frontend is built with React 18, TypeScript, and Vite 6. It utilizes a component-based architecture styled with Tailwind CSS v4 and shadcn/ui.
Compatibility Layer: API Adapter
A critical piece of the architecture is the apiAdapter.ts, which detects the environment (Tauri vs. Web) and chooses the appropriate communication protocol.
- Desktop Mode: Uses
@tauri-apps/api/coretoinvokeRust commands andlistenfor system-wide events. - Web Mode: Uses standard
fetchfor REST API calls andWebSocketsfor real-time streaming, simulating Tauri events via DOMCustomEventdispatching.
Sources: src/lib/apiAdapter.ts:13-50, src/lib/apiAdapter.ts:130-150
Stream Message Handling
The frontend processes streaming output from the Claude binary. The AgentExecution component manages the lifecycle of an agent run, while StreamMessage and ToolWidgets handle the visual rendering of complex data types like diffs, file trees, and search results.
Sources: src/components/AgentExecution.tsx:160-220, src/components/StreamMessage.tsx:75-150
Backend Architecture
The backend is written in Rust and handles high-privileged operations that the browser cannot perform directly.
Core Responsibilities
| Component | Responsibility | Relevant Files |
|---|---|---|
| Process Management | Spawns and manages the claude CLI subprocess, capturing stdout/stderr. | web_server.design.md, AgentExecution.tsx |
| Web Server (Axum) | Provides a REST and WebSocket interface for non-Tauri environments. | web_server.design.md |
| Persistence | Manages application state, agent configurations, and session history in SQLite. | README.md, src/i18n/locales/en.json |
| Security | Implements process isolation and permission controls for agents. | README.md:267-275 |
Sources: README.md:244-256, web_server.design.md:24-35, src-tauri/tauri.conf.json:37-52
Execution Data Flow
When a user submits a prompt, the system follows a specific sequence to execute the command and stream back results.
The sequence demonstrates how commands are routed differently based on the environment but converge at the Rust process manager.
Sources: src/lib/apiAdapter.ts:246-300, src/components/AgentExecution.tsx:185-240, web_server.design.md:55-65
Technical Stack Summary
| Layer | Technology |
|---|---|
| Frontend Framework | React 18, Vite 6, TypeScript |
| Backend Framework | Rust, Tauri 2, Axum (Web Mode) |
| Styling | Tailwind CSS v4, Lucide Icons, Framer Motion |
| State Management | Zustand |
| Database | SQLite (rusqlite) |
| Build Tools | Bun, Cargo |
Sources: package.json:10-75, README.md:234-242
Conclusion
Opcode's architecture is designed for flexibility and security, allowing it to function as a native desktop application while offering a bridge for web-based access. By abstracting communication through an API Adapter and leveraging Rust for subprocess management, it provides a stable environment for complex AI-assisted development tasks.