oh-my-opencode/docs/migration-v2-to-v3.md

Migrating from v2.x to v3.x

v3 brings the Titans. Atlas holds your workflow together. Prometheus plans before you code. Your Sisyphus now has a team.

TL;DR: Upgrade in 60 Seconds

For most users: Just update. Your config probably works.

bunx oh-my-opencode@3 install

Must check:

• Agent names in custom code are lowercase (sisyphus-junior not Sisyphus-Junior)
• disabled_hooks array is updated if you reference old hook names
• Custom delegate_task calls use category + skills (new preferred method)

Works unchanged: All existing config files, Claude Code compatibility, MCPs.

New toys: Atlas orchestrator, Prometheus planner, category-based delegation, skill injection.

---

What's New in v3 (The Good Stuff)

Feature	Description	Why Care
Atlas Orchestrator	Master orchestrator that coordinates complex multi-agent workflows	Your agents now have a traffic controller
Prometheus Planner	Strategic planning with interview mode, creates detailed work plans	Better planning = fewer wrong turns
Metis + Momus	Plan consultant (pre-planning) + reviewer (validation)	Plans get vetted before execution
Category System	delegate_task(category="visual-engineering") routes to optimal model	Right model for the job, automatically
Skills Injection	delegate_task(skills=["git-master"]) adds specialized knowledge	Agents learn new tricks on demand
Model Resolution	3-step fallback: User Override -> Provider Chain -> System Default	Always gets a working model
10 New Hooks	atlas, delegate-task-retry, prometheus-md-only, and more	More control points

---

Breaking Changes Checklist

High Impact (Will break things)

• Agent names are lowercase in API calls

  // v2.x - Mixed case worked
  delegate_task({ agent: "Sisyphus-Junior", prompt: "..." })
  
  // v3.x - Must be lowercase
  delegate_task({ agent: "sisyphus-junior", prompt: "..." })
  

  Affects: Custom tools, scripts calling agents by name
  Fix: Find/replace in your codebase

• Removed agents

  Removed Agent	Migration Path
  document-writer	Use delegate_task(category="writing")
  frontend-ui-ux-engineer	Use delegate_task(category="visual-engineering", skills=["frontend-ui-ux"])

Medium Impact (May affect advanced users)

• Category system is primary delegation method

  // v2.x style (still works)
  delegate_task({ agent: "oracle", prompt: "..." })
  
  // v3.x preferred style
  delegate_task({ 
    category: "ultrabrain", 
    skills: ["git-master"], 
    prompt: "..." 
  })
  

• Hook renames

  v2.x Name	v3.x Name
  anthropic-auto-compact	anthropic-context-window-limit-recovery
  sisyphus-orchestrator	atlas

• Removed hooks (will be filtered out automatically)

  Removed Hook	Reason
  preemptive-compaction	Replaced by anthropic-context-window-limit-recovery
  empty-message-sanitizer	Functionality integrated elsewhere

Low Impact (Mostly additive)

• 10 new hooks added - none renamed or removed

  • New: atlas, delegate-task-retry, prometheus-md-only, compaction-context-injector, start-work, background-notification, task-resume-info, and more
  • Action: Review if you want to disable any

• New built-in skills

  • playwright - Browser automation
  • frontend-ui-ux - UI/UX design patterns
  • git-master - Advanced git operations
  • Disable if unwanted: "disabled_skills": ["frontend-ui-ux"]

---

Upgrade Path

Standard Upgrade (Recommended)

1. Backup your config (optional but wise)

   cp ~/.config/opencode/oh-my-opencode.json ~/.config/opencode/oh-my-opencode.json.v2-backup
   

2. Update the package

   bunx oh-my-opencode@3 install
   

3. Run doctor

   bunx oh-my-opencode doctor --verbose
   

4. Test with a simple task

   ulw fix a typo in README
   

Fresh Install (Nuclear option)

1. Remove old config

   rm -rf ~/.config/opencode/oh-my-opencode.json
   rm -rf .opencode/oh-my-opencode.json
   

2. Run installer

   bunx oh-my-opencode@3 install
   

---

Configuration Changes

New: Category-Based Configuration

v3.x introduces categories for semantic task delegation instead of hardcoded agent names.

Available Categories:

• visual-engineering - UI/UX work (default: Gemini 3 Pro)
• ultrabrain - Complex reasoning (default: GPT-5.2)
• artistry - Creative work
• quick - Fast/cheap tasks (default: GPT-5-nano)
• unspecified-high - High capability (default: Claude Opus 4.5)
• unspecified-low - Low capability (default: Claude Sonnet 4.5)
• writing - Content creation

v2.x Pattern (Direct Agent Calls):

{
  "agents": {
    "document-writer": { "model": "anthropic/claude-opus-4-5" },
    "frontend-ui-ux-engineer": { "model": "google/gemini-3-pro" }
  }
}

v3.x Pattern (Category-Based):

{
  "categories": {
    "writing": { "model": "anthropic/claude-opus-4-5" },
    "visual-engineering": { "model": "google/gemini-3-pro" }
  }
}

New Config Options

Option	Type	Default	Description
categories	object	built-in defaults	Category-based delegation config
categories.*.model	string	varies	Model for category
categories.*.skills	string[]	[]	Auto-inject skills
agents.*.category	string	-	Inherit from category config
agents.*.skills	string[]	[]	Inject skills into agent
disabled_skills	string[]	[]	Disable built-in skills

Config File Example (v3)

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  
  // NEW: Category-based model routing
  "categories": {
    "visual-engineering": { "model": "google/gemini-3-pro" },
    "ultrabrain": { "model": "openai/gpt-5.2-codex" },
    "quick": { "model": "anthropic/claude-haiku-4-5" }
  },
  
  // NEW: Skills can be injected into agents
  "agents": {
    "sisyphus-junior": {
      "skills": ["git-master"]  // Always has git expertise
    }
  },
  
  // UNCHANGED: These still work exactly the same
  "disabled_hooks": ["comment-checker"],
  "disabled_mcps": ["websearch"],
  "disabled_agents": ["multimodal-looker"]
}

Tools to Permissions Migration

v3.x replaces the tools format with permission.

v2.x (Legacy):

{
  "agents": {
    "explore": {
      "tools": {
        "edit": false,
        "bash": false
      }
    }
  }
}

v3.x (Permission-Based):

{
  "agents": {
    "explore": {
      "permission": {
        "edit": "deny",
        "bash": "deny",
        "webfetch": "allow"
      }
    }
  }
}

Permission Values:

• ask - Prompt user for each use
• allow - Always allow
• deny - Always deny

---

API Changes for Plugin Developers

Agent Name Normalization

All agent names are lowercase in API calls. Internal lookup is case-insensitive, but the string you pass must match the normalized form.

// v2.x - Mixed case worked
await callAgent("Sisyphus-Junior", { prompt: "..." })

// v3.x - Must be lowercase
await callAgent("sisyphus-junior", { prompt: "..." })

delegate_task Changes

// v2.x signature (still works)
delegate_task({
  agent: "oracle",
  prompt: "Review this code"
})

// v3.x preferred signature
delegate_task({
  category: "ultrabrain",      // NEW: Route by category
  skills: ["git-master"],       // NEW: Inject skills
  prompt: "Review this code",
  run_in_background: false
})

New Type Definitions

// AgentOverrideConfigSchema additions
{
  category?: string      // NEW: Inherit from category
  skills?: string[]      // NEW: Inject skills
}

// New CategoryConfigSchema
{
  model?: string
  variant?: string
  temperature?: number
  thinking?: { type: "enabled" | "disabled", budgetTokens?: number }
  // ...
}

---

Troubleshooting

"Agent not found: Sisyphus-Junior"

Cause: Agent names are now lowercase.
Fix: Use sisyphus-junior instead of Sisyphus-Junior.

"Category 'business-logic' not found"

Cause: Category was renamed in v3.
Fix: Use ultrabrain for strategic/architecture tasks.

"Model resolution failed"

Cause: No provider available for required model.
Fix:

1. Run bunx oh-my-opencode doctor --verbose
2. Check "Model Resolution" section
3. Either configure the missing provider or override the model

Agents behaving differently

Cause: New orchestration layer (Atlas) changes agent coordination.
Fix:

• If you want v2 behavior: "disabled_hooks": ["atlas"]
• If Atlas is too aggressive: Adjust via sisyphus_agent config

Performance regression

Cause: New hooks add overhead.
Fix: Disable non-critical hooks:

{
  "disabled_hooks": [
    "agent-usage-reminder",
    "auto-update-checker",
    "background-notification"
  ]
}

---

Migration Checklist

Step 1: Update Dependencies

bunx oh-my-opencode@3 install

Step 2: Check Agent Names

Search your codebase for uppercase agent names and convert to lowercase.

Step 3: Update Configuration

// BEFORE (V2.x)
{
  "agents": {
    "document-writer": { "model": "anthropic/claude-opus-4-5" }
  },
  "disabled_hooks": ["anthropic-auto-compact", "sisyphus-orchestrator"]
}

// AFTER (V3.x)
{
  "categories": {
    "writing": { "model": "anthropic/claude-opus-4-5" }
  },
  "disabled_hooks": ["anthropic-context-window-limit-recovery", "atlas"]
}

Step 4: Update Tools to Permissions

// BEFORE
"tools": { "edit": false, "bash": false }

// AFTER  
"permission": { "edit": "deny", "bash": "deny" }

Step 5: Verify

bunx oh-my-opencode doctor

---

Automatic Migration

v3.x automatically handles most changes:

• Agent name renames (case-insensitive)
• Hook name renames
• Config file backup creation
• Removed hooks filtering

Manual steps required:

• Remove document-writer and frontend-ui-ux-engineer agents
• Convert model to category in agent configs (optional, old style still works)
• Convert tools to permission format
• Remove google_auth config option (use external plugin)

---

Reference: Complete Agent List

v3.x Built-in Agents

sisyphus              - Main orchestrator (was: Sisyphus, OmO)
prometheus            - Planner (was: Prometheus (Planner), OmO-Plan)
atlas                 - Orchestrator (was: orchestrator-sisyphus)
sisyphus-junior       - Focused executor
metis                 - Plan consultant (was: Metis (Plan Consultant))
momus                 - Plan reviewer (was: Momus (Plan Reviewer))
oracle                - Debugging & architecture
librarian             - Docs & code search
explore               - Fast codebase grep
multimodal-looker     - Image/PDF analysis

v3.x Built-in Categories

visual-engineering    - UI/UX work
ultrabrain           - Complex reasoning
artistry             - Creative work
quick                - Fast/cheap tasks
unspecified-high     - High capability
unspecified-low      - Low capability
writing              - Content creation

---

Need Help?

• Full v3 Documentation
• Discord Community
• Report Migration Issues