oh-my-opencode

Multi-agent orchestration plugin for OpenCode. Use when the user wants to install, configure, or operate oh-my-opencode — including agent delegation, ultrawork mode, Prometheus planning, background tasks, category-based task routing, model resolution, tmux integration, or any oh-my-opencode feature. Covers installation, configuration, all agents (Sisyphus, Oracle, Librarian, Explore, Atlas, Prometheus, Metis, Momus), all categories, slash commands, hooks, skills, MCPs, and troubleshooting.

# Oh My OpenCode

Multi-agent orchestration plugin that transforms OpenCode into a full agent harness with specialized agents, background task execution, category-based model routing, and autonomous work modes.

**Package**: `oh-my-opencode` (install via `bunx oh-my-opencode install`)
**Repository**: https://github.com/code-yeongyu/oh-my-opencode
**Schema**: https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json

---

## Prerequisites

1. **OpenCode** installed and configured (`opencode --version` should be 1.0.150+)
   ```bash
   curl -fsSL https://opencode.ai/install | bash
   # or: npm install -g opencode-ai
   # or: bun install -g opencode-ai
   ```
2. At least one LLM provider authenticated (`opencode auth login`)
3. **Strongly recommended**: Anthropic Claude Pro/Max subscription (Sisyphus uses Claude Opus 4.5)

---

## Installation

Run the interactive installer:

```bash
bunx oh-my-opencode install
```

Non-interactive mode with provider flags:

```bash
bunx oh-my-opencode install --no-tui \
  --claude=<yes|no|max20> \
  --openai=<yes|no> \
  --gemini=<yes|no> \
  --copilot=<yes|no> \
  --opencode-zen=<yes|no> \
  --zai-coding-plan=<yes|no>
```

Verify:

```bash
opencode --version
cat ~/.config/opencode/opencode.json  # should contain "oh-my-opencode" in plugin array
```

---

## Two Workflow Modes

### Mode 1: Ultrawork (Quick Autonomous Work)

Include `ultrawork` or `ulw` in your prompt. That's it.

```
ulw add authentication to my Next.js app
```

The agent will automatically:
1. Explore your codebase to understand existing patterns
2. Research best practices via specialized background agents
3. Implement the feature following your conventions
4. Verify with diagnostics and tests
5. Keep working until 100% complete

### Mode 2: Prometheus (Precise Planned Work)

For complex or critical tasks:

1. **Press Tab** → switches to Prometheus (Planner) mode
2. **Describe your work** → Prometheus interviews you, asking clarifying questions while researching your codebase
3. **Confirm the plan** → review generated plan in `.sisyphus/plans/*.md`
4. **Run `/start-work`** → Atlas orchestrator takes over:
   - Distributes tasks to specialized sub-agents
   - Verifies each task completion independently
   - Accumulates learnings across tasks
   - Tracks progress across sessions (resume anytime)

**Critical rule**: Do NOT use Atlas without `/start-work`. Prometheus and Atlas are a pair — always use them together.

---

## Agents

All agents are enabled by default. Each has a default model and provider priority fallback chain.

| Agent | Role | Default Model | Provider Priority Chain |
|-------|------|---------------|------------------------|
| **Sisyphus** | Primary orchestrator | `claude-opus-4-5` | anthropic → kimi-for-coding → zai-coding-plan → openai → google |
| **Sisyphus-Junior** | Focused task executor (used by `delegate_task` with categories) | Determined by category | Per-category chain |
| **Hephaestus** | Autonomous deep worker — goal-oriented, explores before acting | `gpt-5.2-codex` (medium) | openai → github-copilot → opencode (requires gpt-5.2-codex) |
| **Oracle** | Architecture, debugging, high-IQ reasoning (read-only) | `gpt-5.2` | openai → google → anthropic |
| **Librarian** | Official docs, OSS search, remote codebase analysis | `glm-4.7` | zai-coding-plan → opencode → anthropic |
| **Explore** | Fast codebase grep (contextual search) | `claude-haiku-4-5` | anthropic → github-copilot → opencode |
| **Multimodal Looker** | Image/PDF/diagram analysis | `gemini-3-flash` | google → openai → zai-coding-plan → kimi-for-coding → anthropic → opencode |
| **Prometheus** | Work planner (interview-based plan generation) | `claude-opus-4-5` | anthropic → kimi-for-coding → openai → google |
| **Metis** | Pre-planning consultant (ambiguity/failure-point analysis) | `claude-opus-4-5` | anthropic → kimi-for-coding → openai → google |
| **Momus** | Plan reviewer (clarity, verifiability, completeness) | `gpt-5.2` | openai → anthropic → google |
| **Atlas** | Plan orchestrator (executes Prometheus plans via `/start-work`) | `k2p5` / `claude-sonnet-4-5` | kimi-for-coding → opencode → anthropic → openai → google |
| **OpenCode-Builder** | Default build agent (disabled by default when Sisyphus is active) | System default | System default |

### Agent Invocation

Agents are invoked via `delegate_task()` or the `--agent` CLI flag — NOT with `@` prefix.

```javascript
// Invoke a specific agent
delegate_task(subagent_type="oracle", prompt="Review this architecture...")

// Invoke via category (routes to Sisyphus-Junior with category model)
delegate_task(category="visual-engineering", load_skills=["frontend-ui-ux"], prompt="...")

// Background execution (non-blocking)
delegate_task(subagent_type="explore", run_in_background=true, prompt="Find auth patterns...")
```

CLI:

```bash
opencode --agent oracle
opencode run --agent librarian "Explain how auth works in this codebase"
```

### When to Use Which Agent

| Situation | Agent |
|-----------|-------|
| General coding tasks | Sisyphus (default) |
| Autonomous goal-oriented deep work | Hephaestus (requires gpt-5.2-codex) |
| Architecture decisions, debugging after 2+ failures | Oracle |
| Looking up library docs, finding OSS examples | Librarian |
| Finding code patterns in your codebase | Explore |
| Analyzing images, PDFs, diagrams | Multimodal Looker |
| Complex multi-day projects needing a plan | Prometheus + Atlas (via Tab → `/start-work`) |
| Pre-planning scope analysis | Metis |
| Reviewing a generated plan for gaps | Momus |
| Quick single-file changes | delegate_task with `quick` category |

---

## Categories

Categories route tasks to Sisyphus-Junior with domain-optimized models via `delegate_task()`.

| Category | Default Model | Variant | Provider Priority Chain | Best For |
|----------|---------------|---------|------------------------|----------|
| `visual-engineering` | `gemini-3-pro` | — | google → anthropic → zai-coding-plan | Frontend, UI/UX, design, styling, animation |
| `ultrabrain` | `gpt-5.2-codex` | `xhigh` | openai → google → anthropic | Deep logical reasoning, complex architecture |
| `deep` | `gpt-5.2-codex` | `medium` | openai → anthropic → google | Goal-oriented autonomous problem-solving (Hephaestus-style) |
| `artistry` | `gemini-3-pro` | `max` | google → anthropic → openai | Creative/novel approaches, unconventional solutions |
| `quick` | `claude-haiku-4-5` | — | anthropic → google → opencode | Trivial tasks, single file changes, typo fixes |
| `unspecified-low` | `claude-sonnet-4-5` | — | anthropic → openai → google | General tasks, low effort |
| `unspecified-high` | `claude-opus-4-5` | `max` | anthropic → openai → google | General tasks, high effort |
| `writing` | `gemini-3-flash` | — | google → anthropic → zai-coding-plan → openai | Documentation, prose, technical writing |

### Category Usage

```javascript
delegate_task(category="visual-engineering", load_skills=["frontend-ui-ux"], prompt="Create a dashboard component")
delegate_task(category="ultrabrain", load_skills=[], prompt="Design the payment processing flow")
delegate_task(category="quick", load_skills=["git-master"], prompt="Fix the typo in README.md")
delegate_task(category="deep", load_skills=[], prompt="Investigate and fix the memory leak in the worker pool")
```

### Critical: Model Resolution Priority

Categories do NOT use their built-in defaults unless configured. Resolution order:

1. **User-configured model** (in `oh-my-opencode.json`) — highest priority
2. **Category's built-in default** (if category is in config)
3. **System default model** (from `opencode.json`) — fallback

To use optimal models, add categories to your config. See [references/configuration.md](references/configuration.md).

---

## Built-in Skills

| Skill | Purpose | Usage |
|-------|---------|-------|
| `playwright` | Browser automation via Playwright MCP (default browser engine) |