Installation and Setup
Relevant source files
The following files were used as context for generating this wiki page:
Opcode is a desktop GUI and toolkit designed to manage Claude Code sessions, custom agents, and MCP servers. The installation process involves setting up the core Claude Code CLI and then either using pre-built executables or building the application from source using a combination of Rust (Tauri 2) and React (TypeScript).
Sources: README.md:16-24, README.md:144-149
Core Prerequisites
Before installing Opcode, the system must have the Claude Code CLI installed. Opcode functions as a visual wrapper and command center for this CLI. The claude command must be available in the system's PATH.
Sources: README.md:150-152, README.md:256-258
System Requirements
| Component | Minimum Requirement |
|---|---|
| OS | Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+) |
| RAM | 4GB (8GB recommended) |
| Storage | 1GB free space |
Sources: README.md:159-162
Required Build Tools
To build Opcode from source, the following development environment tools are necessary:
- Rust (1.70.0+): Used for the Tauri backend.
- Bun: The primary package manager for the frontend.
- Git: For repository cloning and version control.
- Node.js Dependencies: Handled via Bun (React 18, TypeScript, Vite 6).
Sources: README.md:165-182, package.json:54-94
Platform-Specific Dependencies
Installation requires specific system libraries depending on the target environment to support the Tauri 2 framework.
Linux (Ubuntu/Debian)
Developers must install webkit2gtk and other GTK-related development packages:
sudo apt install -y libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev build-essential libssl-dev libsoup-3.0-dev libjavascriptcoregtk-4.1-dev
Sources: README.md:186-200, src-tauri/tauri.conf.json:80-82
macOS
Requires Xcode Command Line Tools (xcode-select --install). Opcode supports universal binaries for both Intel and Apple Silicon architectures.
Sources: README.md:203-207, README.md:235-237
Windows
Requires Microsoft C++ Build Tools and WebView2 (which is typically pre-installed on Windows 11).
Sources: README.md:210-212
Build and Setup Flow
The following diagram illustrates the lifecycle of setting up the Opcode development environment and building the application.
The build process utilizes bun to handle frontend assets and tauri-cli to compile the Rust backend and bundle the final application.
Sources: README.md:215-245, package.json:7-17
Web Server Mode Setup
Opcode includes an alternative web server mode (using Axum) that allows access via mobile devices or browsers without the Tauri desktop shell.
Architecture Overview
The web server architecture differs from the desktop version by utilizing WebSockets for real-time streaming and a REST API for session management.
Starting the Web Server
For development in web mode, the just command runner is used:
nix-shell --run 'just web'
This builds the frontend and starts the Rust server on port 8080.
Sources: web_server.design.md:65-68
Initial Configuration
Upon the first launch of Opcode, the application performs an automatic setup sequence:
- Directory Detection: Locates the
~/.claudedirectory. - Project Scanning: Scans
~/.claude/projects/to populate the visual project browser. - Database Initialization: Sets up a local SQLite database (via
rusqlite) for agents, run history, and settings.
Sources: README.md:72-76, README.md:310-313, src/i18n/locales/en.json:444-450
Conclusion
Installation of Opcode is primarily focused on ensuring the Claude Code CLI is present and the appropriate platform build tools (Rust and Bun) are configured. Once built, the application manages the user's environment by localizing all storage in ~/.claude and utilizing a local SQLite database for persistent state.
Sources: README.md:323-328, src/i18n/locales/en.json:444-450