Quick Start

This guide will help you install and configure Oh My OpenCode in minutes, experiencing the power of multi-agent collaboration.

Prerequisites

Before you begin, make sure you have:

✅ Installed OpenCode
✅ One of the following subscriptions:
- Claude Max20 (recommended) - The most powerful multi-agent experience
- ChatGPT Plus/Pro - Good performance and cost balance
- Gemini Advanced - High value for money
✅ Configured basic OpenCode settings (API keys, etc.)

Installation Steps

Method 1: Installation for Human Users

If you’re a human user, follow these steps to install:

# 1. Clone the Oh My OpenCode repository
git clone https://github.com/code-yeongyu/oh-my-opencode.git ~/.oh-my-opencode

# 2. Install dependencies
cd ~/.oh-my-opencode
npm install  # or yarn install / pnpm install

# 3. Run the installation script
npm run install

The installation script will automatically:

Detect your OpenCode configuration file location
Back up existing configuration
Merge Oh My OpenCode configuration into your OpenCode settings

Method 2: Installation for AI Agents

If you’re using an AI agent to install, the agent can directly use:

# AI agents can directly run the installation script
opencode "Install oh-my-opencode using ultrawork mode"

The AI agent will automatically handle:

Download and configuration
Dependency installation
Configuration file merging

Subscription Plan Configuration

Choose the configuration based on your subscription service:

Claude Max20 (Recommended)

{
  "subscription": "claude-max20",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 3
  },
  "agents": {
    "oracle": { "enabled": true },
    "librarian": { "enabled": true },
    "frontend-engineer": { "enabled": true },
    "backend-engineer": { "enabled": true },
    "explore": { "enabled": true }
  }
}

Features:

Highest concurrent task count (3 background tasks)
All agents fully enabled
Best multi-agent collaboration experience

ChatGPT Plus/Pro

{
  "subscription": "chatgpt-plus",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": { "enabled": true },
    "librarian": { "enabled": true },
    "frontend-engineer": { "enabled": true }
  }
}

Features:

Medium concurrent task count (2 background tasks)
Core agents enabled
Good performance and cost balance

Gemini Advanced

{
  "subscription": "gemini-advanced",
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2
  },
  "agents": {
    "oracle": { "enabled": false },
    "librarian": { "enabled": true },
    "explore": { "enabled": true }
  }
}

Features:

Medium concurrent task count (2 background tasks)
Selected agents enabled
High value for money

Verify Installation

After installation, verify that Oh My OpenCode is working correctly:

1. Check Configuration File

# View Oh My OpenCode configuration file
cat .opencode/oh-my-opencode.json  # Project-level configuration
# or
cat ~/.config/opencode/oh-my-opencode.json  # User-level configuration (macOS/Linux)
# or
type %APPDATA%\opencode\oh-my-opencode.json  # User-level configuration (Windows)

Confirm that the configuration file contains Oh My OpenCode related settings.

2. Test Basic Functionality

# Test Sisyphus agent
opencode "Use @oracle to analyze the architecture of the current project"

# Test ultrawork mode
opencode "ulw: List all configuration files in the project"

3. Check Agent List

# View all available agents
opencode "List all available specialist agents"

You should see output similar to:

Available agents:
- @oracle - System architecture design
- @librarian - Documentation research
- @frontend-engineer - Frontend development
- @backend-engineer - Backend development
- @explore - Code base analysis

Basic Configuration

Enable ultrawork Mode

Add ultrawork or ulw keyword to your task description:

opencode "ultrawork: Refactor user authentication module"

This will automatically enable:

✅ All configured agents
✅ Background task parallelization
✅ LSP tool integration
✅ Intelligent context management

Customize Agent Behavior

Edit the OpenCode configuration file to add agent-specific settings:

{
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "claude-sonnet-4",
      "temperature": 0.7,
      "prompt_append": "Please provide detailed technical decision rationale"
    }
  }
}

Configure Background Task Concurrency

Control the number of background tasks running simultaneously:

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  }
}

Common Issues

Installation Failed

Problem: Installation script errors or cannot find OpenCode configuration

Solution:

Confirm OpenCode is installed correctly: opencode --version

Manually specify the configuration file path:

export OPENCODE_CONFIG_PATH=/path/to/your/config.json
npm run install

Agent Not Responding

Problem: No response when using @oracle and other agents

Solution:

Check if the agent is enabled:
```
opencode "Show current configuration"
```
Confirm the subscription plan supports the agent
Check if API quota is exhausted

Configuration Conflict

Problem: Oh My OpenCode configuration conflicts with existing configuration

Solution:

View backup file:
- Project-level: .opencode/oh-my-opencode.json.backup
- User-level (macOS/Linux): ~/.config/opencode/oh-my-opencode.json.backup

Manually merge configuration:

# Restore backup (project-level example)
cp .opencode/oh-my-opencode.json.backup .opencode/oh-my-opencode.json

# Or restore user-level backup (macOS/Linux)
cp ~/.config/opencode/oh-my-opencode.json.backup ~/.config/opencode/oh-my-opencode.json

# Manually add Oh My OpenCode configuration
# Edit configuration file, add necessary agents and sisyphus sections

LSP Tools Not Working

Problem: Agents cannot use hover, goto and other LSP functions

Solution:

Confirm the project has initialized LSP server:

# For TypeScript projects
npm install -D typescript

# For Python projects
pip install python-lsp-server

Check LSP configuration:

{
  "lsp": {
    "enabled": true,
    "languages": ["typescript", "python", "go"]
  }
}

Too Many Concurrent Tasks

Problem: Too many background tasks causing performance degradation or API rate limiting

Solution: Reduce the number of concurrent tasks:

{
  "sisyphus": {
    "max_concurrent_tasks": 1  // Reduce to 1
  }
}

Next Steps

After installation, we recommend you:

📖 Read Core Features to learn about all features
🎯 Check Best Practices to learn efficient usage tips
⚙️ Explore Advanced Configuration for deep customization
💡 Refer to Use Cases for inspiration

Get Help

Encountering issues?

📖 Check the GitHub README
🐛 Submit an Issue
💬 Join community discussions

Ready to experience the power of multi-agent collaboration? Try this command:

opencode "ultrawork: Analyze current project and provide improvement suggestions"