opcode

A powerful GUI app and Toolkit for Claude Code

Manage projects, create intelligent agents, track usage, handle MCP servers, and access Claude Code through a beautiful desktop interface.

opcode-demo.mp4

Tip

⭐ Star the repo and follow @getAsterisk on X for early access to asteria-swe-v0.

Note

This project is not affiliated with, endorsed by, or sponsored by Anthropic. Claude is a trademark of Anthropic, PBC. This is an independent developer project using Claude.

🌟 Overview

opcode is a comprehensive desktop application that transforms how you interact with Claude Code. Built with Tauri 2 and React, it provides a beautiful GUI for managing projects, creating intelligent agents, tracking usage, handling MCP servers, and much more.

Think of opcode as your complete command center for Claude Code - bridging the gap between command-line tools and a visual experience that makes AI-assisted development more intuitive, organized, and productive.

📋 Table of Contents

• 🌟 Overview
• ✨ Features
  • 🗂️ Project & Session Management
  • 🤖 CC Agents
  • 📊 Usage Analytics Dashboard
  • 🔌 MCP Server Management
  • ⏰ Timeline & Checkpoints
  • 📝 CLAUDE.md Management
  • 🌐 Web Server Mode
  • ⚙️ Proxy & Settings
  • 🔧 Slash Commands
• 📖 Usage
  • Getting Started
  • Managing Projects
  • Creating Agents
  • Tracking Usage
  • Working with MCP Servers
• 🚀 Installation
• 🔨 Build from Source
• 🛠️ Development
• 🔒 Security
• 🤝 Contributing
• 📄 License
• 🙏 Acknowledgments

✨ Features

🗂️ Project & Session Management

• Visual Project Browser: Navigate through all your Claude Code projects in ~/.claude/projects/
• Session History: View and resume past coding sessions with full context
• Smart Search: Find projects and sessions quickly with built-in search
• Session Insights: See first messages, timestamps, and session metadata at a glance

🤖 CC Agents

• Custom AI Agents: Create specialized agents with custom system prompts and behaviors
• Agent Library: Build a collection of purpose-built agents for different tasks
• Background Execution: Run agents in separate processes for non-blocking operations
• Execution History: Track all agent runs with detailed logs and performance metrics
• GitHub Integration: Browse and import agents directly from GitHub
• Agent Export/Import: Share agent configurations with others
• Real-time Monitoring: Live output streaming and execution status
• Permission Control: Fine-grained file read/write and network access permissions

📊 Usage Analytics Dashboard

• Cost Tracking: Monitor your Claude API usage and costs in real-time
• Token Analytics: Detailed breakdown by model, project, and time period
• Visual Charts: Beautiful charts showing usage trends and patterns
• Export Data: Export usage data for accounting and analysis

🔌 MCP Server Management

• Server Registry: Manage Model Context Protocol servers from a central UI
• Easy Configuration: Add servers via UI or import from existing configs
• Connection Testing: Verify server connectivity before use
• Claude Desktop Import: Import server configurations from Claude Desktop

⏰ Timeline & Checkpoints

• Session Versioning: Create checkpoints at any point in your coding session
• Visual Timeline: Navigate through your session history with a branching timeline
• Instant Restore: Jump back to any checkpoint with one click
• Fork Sessions: Create new branches from existing checkpoints
• Diff Viewer: See exactly what changed between checkpoints
• File Tracking: Automatic tracking of file changes between checkpoints
• Auto Checkpoints: Configurable automatic checkpoint creation
• Timeline Stats: View comprehensive session statistics and metadata

📝 CLAUDE.md Management

• Built-in Editor: Edit CLAUDE.md files directly within the app
• Live Preview: See your markdown rendered in real-time
• Project Scanner: Find all CLAUDE.md files in your projects
• Syntax Highlighting: Full markdown support with syntax highlighting
• File Browser Integration: Seamlessly browse and edit files within projects

🌐 Web Server Mode

• Browser Access: Access opcode features through any web browser
• WebSocket Support: Real-time Claude interaction via WebSocket
• Mobile Friendly: Optimized for mobile and tablet devices
• Remote Access: Access your Claude sessions from anywhere
• Cross-Platform: Works on any device with a modern browser

⚙️ Proxy & Settings

• Proxy Configuration: Support for HTTP, HTTPS, and SOCKS proxies
• Claude Binary Management: Auto-detection and manual configuration of Claude CLI
• Global Shortcuts: System-wide keyboard shortcuts
• System Integration: Deep integration with macOS, Windows, and Linux

🔧 Slash Commands

• Custom Commands: Create and manage custom slash commands
• Command Library: Build a collection of reusable commands
• Quick Access: Fast command execution from anywhere in the app

📖 Usage

Getting Started

1. Launch opcode: Open the application after installation
2. Welcome Screen: Choose between CC Agents or Projects
3. First Time Setup: opcode will automatically detect your ~/.claude directory

Managing Projects

Projects → Select Project → View Sessions → Resume or Start New

• Click on any project to view its sessions
• Each session shows the first message and timestamp
• Resume sessions directly or start new ones

Creating Agents

CC Agents → Create Agent → Configure → Execute

1. Design Your Agent: Set name, icon, and system prompt
2. Configure Model: Choose between available Claude models
3. Set Permissions: Configure file read/write and network access
4. Execute Tasks: Run your agent on any project

Tracking Usage

Menu → Usage Dashboard → View Analytics

• Monitor costs by model, project, and date
• Export data for reports
• Set up usage alerts (coming soon)

Working with MCP Servers

Menu → MCP Manager → Add Server → Configure

• Add servers manually or via JSON
• Import from Claude Desktop configuration
• Test connections before using

🚀 Installation

Prerequisites

• Claude Code CLI: Install from Claude's official site
• WebView2 (Windows 10/11): Usually pre-installed on Windows 11

Release Downloads

Pre-built executables are available for Windows, macOS, and Linux. Check the Releases page for downloads.

Installation Methods

Windows

1. Download opcode-setup.exe from the releases page
2. Run the installer and follow the prompts
3. Launch opcode from Start Menu or Desktop

macOS

1. Download opcode.dmg from the releases page
2. Open the DMG and drag opcode to Applications
3. Launch from Applications folder

Linux

1. Download the appropriate package (.deb, .AppImage, or .rpm)
2. Install using your package manager or run the AppImage
3. Launch from your application menu

Note

On Linux, you may need to make the AppImage executable: chmod +x opcode.AppImage

🔨 Build from Source

Prerequisites

Before building opcode from source, ensure you have the following installed:

System Requirements

• Operating System: Windows 10/11, macOS 11+, or Linux (Ubuntu 20.04+)
• RAM: Minimum 4GB (8GB recommended)
• Storage: At least 1GB free space

Required Tools

1. Rust (1.70.0 or later)

   # Install via rustup
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Bun (latest version)

   # Install bun
   curl -fsSL https://bun.sh/install | bash

3. Git

   # Usually pre-installed, but if not:
   # Ubuntu/Debian: sudo apt install git
   # macOS: brew install git
   # Windows: Download from https://git-scm.com

4. Claude Code CLI

   • Download and install from Claude's official site
   • Ensure claude is available in your PATH

Platform-Specific Dependencies

Linux (Ubuntu/Debian)

# Install system dependencies
sudo apt update
sudo apt install -y \
  libwebkit2gtk-4.1-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev \
  patchelf \
  build-essential \
  curl \
  wget \
  file \
  libssl-dev \
  libxdo-dev \
  libsoup-3.0-dev \
  libjavascriptcoregtk-4.1-dev

macOS

# Install Xcode Command Line Tools
xcode-select --install

# Install additional dependencies via Homebrew (optional)
brew install pkg-config

Windows

• Install Microsoft C++ Build Tools
• Install WebView2 (usually pre-installed on Windows 11)

Build Steps

1. Clone the Repository

   git clone https://github.com/getAsterisk/opcode.git
   cd opcode

2. Install Frontend Dependencies

   bun install

3. Build the Application

   For Development (with hot reload)

   bun run tauri dev

   For Production Build

   # Build the application
   bun run tauri build
   
   # The built executable will be in:
   # - Linux: src-tauri/target/release/
   # - macOS: src-tauri/target/release/
   # - Windows: src-tauri/target/release/

4. Platform-Specific Build Options

   Debug Build (faster compilation, larger binary)

   bun run tauri build --debug

   Universal Binary for macOS (Intel + Apple Silicon)

   bun run tauri build --target universal-apple-darwin

Troubleshooting

Common Issues

1. "cargo not found" error

   • Ensure Rust is installed and ~/.cargo/bin is in your PATH
   • Run source ~/.cargo/env or restart your terminal

2. Linux: "webkit2gtk not found" error

   • Install the webkit2gtk development packages listed above
   • On newer Ubuntu versions, you might need libwebkit2gtk-4.0-dev

3. Windows: "MSVC not found" error

   • Install Visual Studio Build Tools with C++ support
   • Restart your terminal after installation

4. "claude command not found" error

   • Ensure Claude Code CLI is installed and in your PATH
   • Test with claude --version

5. Build fails with "out of memory"

   • Try building with fewer parallel jobs: cargo build -j 2
   • Close other applications to free up RAM

Verify Your Build

After building, you can verify the application works:

# Run the built executable directly
# Linux/macOS
./src-tauri/target/release/opcode

# Windows
./src-tauri/target/release/opcode.exe

Build Artifacts

The build process creates several artifacts:

• Executable: The main opcode application
• Installers (when using tauri build):
  • .deb package (Linux)
  • .AppImage (Linux)
  • .dmg installer (macOS)
  • .msi installer (Windows)
  • .exe installer (Windows)

All artifacts are located in src-tauri/target/release/.

📦 Version Management

opcode uses a simplified version management system that automatically handles version synchronization and executable naming.

Version Format

Versions follow Semantic Versioning (SemVer): x.y.z

• x (Major): Major version - incompatible API changes
• y (Minor): Minor version - backward-compatible new features
• z (Patch): Patch version - backward-compatible bug fixes (auto-increments on build)

Version Management Workflow

Single Source of Truth

The version number is managed only in package.json:

{
  "name": "opcode",
  "version": "0.2.1",
  ...
}

How It Works

1. Manual Editing for x.y: When releasing a new version, manually edit package.json to set the version (e.g., change 0.2.1 to 1.0.0)

2. Sync Version: Run the sync command to propagate the version to all configuration files:

   npm run sync:version

   This updates:

   • src-tauri/Cargo.toml - Rust crate version
   • src-tauri/tauri.conf.json - Tauri app version

3. Auto-Increment on Build: Every build automatically increments the patch version (z):

   # The prebuild hook automatically:
   # - Increments patch version (0.2.1 → 0.2.2)
   # - Syncs version to all files
   bun run tauri build
   
   # Then the build continues and the post-build hook:
   # - Renames executable with version suffix
   # Output: opcode-v0.2.2.exe

Example Release Workflow

Scenario 1: Release a new minor version

# 1. Manually edit package.json: "version": "1.5.0"
# 2. Sync version to other files
npm run sync:version

# 3. Build (automatically increments to 1.5.1)
bun run tauri build

# Output: opcode-v1.5.1.exe

Scenario 2: Quick bug fix

# Build directly (no manual version change needed)
bun run tauri build
# Version automatically: 1.5.1 → 1.5.2
# Output: opcode-v1.5.2.exe

Version Display

The current version is displayed in multiple places:

1. NFO Credits Window: Click the "i" icon in the title bar

   • Window title shows: opcode.NFO v0.2.1
   • Credits header shows: opcode v0.2.1

2. Build Output: Executables include version suffix

   • opcode-v0.2.1.exe (Windows)
   • opcode-v0.2.1.AppImage (Linux)
   • opcode-v0.2.1.dmg (macOS)

Available Commands

# Sync version from package.json to all config files
npm run sync:version

# Build production version (auto-increments patch, adds version suffix)
bun run tauri build

# Build debug version (also auto-increments)
bun run tauri build --debug

# Development build (also auto-increments)
bun run tauri dev

Key Principles

• ✅ Single source: Version only managed in package.json
• ✅ Manual x.y: You control major and minor versions
• ✅ Auto z: Patch version increments automatically on every build
• ✅ No auto-reset: Patch version does NOT reset to 0 when x.y changes
• ✅ Manual reset: Set z to 0 manually when needed (e.g., 2.0.0)
• ✅ Automatic sync: Version syncs to all files during build
• ✅ Versioned executables: Built files include version suffix

Note

The patch version (z) never automatically resets to zero. When you want to release 2.0.0, manually edit package.json to set the version, then build. The build will increment it to 2.0.1 for the actual executable.

🛠️ Development

Tech Stack

• Frontend: React 18 + TypeScript + Vite 6
• Backend: Rust with Tauri 2
• UI Framework: Tailwind CSS v4 + shadcn/ui + Radix UI
• State Management: Zustand
• Database: SQLite (via rusqlite)
• Web Server: Axum (with WebSocket support)
• Package Manager: Bun
• Process Management: Tokio (async runtime)
• Data Visualization: Recharts

Project Structure

opcode/
├── src/                          # React frontend
│   ├── components/               # UI components
│   │   ├── ui/                   # shadcn/ui base components
│   │   ├── claude-code-session/  # Claude session components
│   │   ├── Agent*.tsx            # Agent management
│   │   ├── FilePicker.tsx        # File browser
│   │   └── ...
│   ├── lib/                      # Utilities & API
│   │   ├── api.ts                # Tauri API client
│   │   ├── apiAdapter.ts         # Desktop/Web adapter
│   │   └── analytics/            # Analytics module
│   ├── stores/                   # Zustand state stores
│   ├── services/                 # Business logic
│   ├── hooks/                    # Custom React hooks
│   └── types/                    # TypeScript definitions
├── src-tauri/                    # Rust backend
│   ├── src/
│   │   ├── commands/             # Tauri command handlers
│   │   │   ├── agents.rs         # Agent management
│   │   │   ├── claude.rs         # Claude interactions
│   │   │   ├── mcp.rs            # MCP server management
│   │   │   ├── storage.rs        # SQLite operations
│   │   │   └── usage.rs          # Usage analytics
│   │   ├── checkpoint/           # Checkpoint system
│   │   │   ├── manager.rs        # Timeline management
│   │   │   └── storage.rs        # Checkpoint persistence
│   │   ├── process/              # Process management
│   │   │   └── registry.rs       # Process registry
│   │   ├── web_server.rs         # Axum web server
│   │   └── main.rs               # Tauri entry point
│   ├── capabilities/             # Tauri permissions
│   └── tauri.conf.json           # Tauri configuration
├── cc_agents/                    # CC agent configs
├── justfile                      # Build tasks
└── package.json                  # Frontend dependencies

Development Commands

# Install dependencies
bun install

# Start development server (with hot reload)
bun run tauri dev

# Run frontend only
bun run dev

# Type checking
bunx tsc --noEmit

# Run Rust tests
cd src-tauri && cargo test

# Format Rust code
cd src-tauri && cargo fmt

# Check Rust code with clippy
cd src-tauri && cargo clippy

# Build production version
bun run tauri build

# Build debug version (faster)
bun run tauri build --debug

# Clean build artifacts
just clean  # or manually:
rm -rf node_modules dist
cd src-tauri && cargo clean

Just Commands (Optional)

If you have just installed, additional commands are available:

# View all available commands
just

# Quick build and run
just run

# Start web server mode
just web

# Get local IP (for mobile access)
just ip

# Full rebuild
just rebuild

🔒 Security

opcode prioritizes your privacy and security:

1. Process Isolation: Agents run in separate, isolated processes
2. Permission Control: Configure fine-grained file read/write and network access per agent
3. Local Storage: All data stays on your machine (SQLite database)
4. No Telemetry: Zero data collection or tracking
5. Open Source: Full transparency through open source code
6. API Validation: All frontend inputs validated in the backend
7. Secure Communication: WebSocket connections for real-time features
8. File System Security: Tauri capabilities system controls filesystem access

Warning

While opcode provides security features, always review agent configurations and permissions before execution, especially when dealing with sensitive projects or data.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Areas for Contribution

• 🐛 Bug fixes and improvements
• ✨ New features and enhancements
• 📚 Documentation improvements
• 🎨 UI/UX enhancements
• 🧪 Test coverage improvements
• 🌐 Internationalization (i18n)
• 🔧 Performance optimizations
• 📊 Analytics and reporting features
• 🌐 Web server mode improvements

Development Setup Tips

1. Enable Debug Logging: Set RUST_LOG=debug environment variable for detailed logs
2. Use VS Code: Install the recommended extensions for Rust and TypeScript
3. Browser DevTools: Use F12 in the app to debug the frontend
4. Database Viewer: Use any SQLite browser to inspect the local database

📄 License

This project is licensed under the AGPL License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Tauri - The secure framework for building desktop apps
• Claude by Anthropic

---

Made with ❤️ by the Asterisk

Report Bug · Request Feature

Star History