SKILL: oh-my-opencode (OMO) Ralph Wiggum Loop & Agent Invocation — correct usage, pitfalls, agent behavior observations

skill-oh-my-opencode-ralph-loop.md

Skill: oh-my-opencode (OMO) — Ralph Wiggum Loop & Agent Invocation

Learnings from using OMO to autonomously implement multi-phase Rust projects.

---

What is oh-my-opencode?

oh-my-opencode is an OpenCode plugin that adds:

• Ralph Wiggum loop — runs the agent until ALL todos complete, not just one turn
• Named agents (Sisyphus, Hephaestus, Oracle, Prometheus, Atlas, Librarian, Explore)
• Ultrawork mode (ultrawork or ulw in prompt) — activates all agents for the turn
• Background task management — child sessions idle before parent exits

The key difference from stock opencode run:

opencode run	npx oh-my-opencode run
Exits when model finishes current turn	Waits until all todos complete and all background child sessions are idle
No task enforcement	Ralph Wiggum loop — will keep retrying failed todos
Uses default model	Uses agent-configured model

---

Installation

OMO is distributed on npm. With the opencode.json plugin configuration it loads automatically when opencode starts, but the run command must be invoked via npx:

# Check version
npx oh-my-opencode --version

# Install (interactive)
npx oh-my-opencode install

# Or non-interactive
npx oh-my-opencode install --no-tui --claude=no --gemini=no --copilot=no

Config locations:

• Plugin registration: ~/.config/opencode/opencode.json → "plugin": ["oh-my-opencode@latest"]
• Agent config: ~/.config/opencode/oh-my-opencode.json

---

Correct Invocation

# Basic (uses Sisyphus by default)
npx oh-my-opencode run "Fix the bug in index.ts"

# Named agent
npx oh-my-opencode run --agent hephaestus "Implement feature X"

# With working directory
npx oh-my-opencode run --agent hephaestus --directory /path/to/project "prompt"

# Resume existing session (ralph loop continues from where it left off)
npx oh-my-opencode run --session-id ses_abc123 "Continue: still need to add dev deps"

# Get structured JSON result
npx oh-my-opencode run --json "Fix the bug" | jq .sessionId

# Run after completion hook
npx oh-my-opencode run --on-complete "notify-send Done" "Implement feature"

Agent resolution order:

1. --agent flag
2. OPENCODE_DEFAULT_AGENT env var
3. oh-my-opencode.json → "default_run_agent"
4. Sisyphus (fallback)

---

Available Core Agents

Agent	Designed For	Notes
Sisyphus	Main orchestrator	Multi-step planning + execution, never gives up
Hephaestus	Autonomous deep worker	Best for implementation tasks; reads codebase before acting
Prometheus	Strategic planner	Interview-mode planning before execution
Atlas	General purpose	Balanced; less focused than Hephaestus
Oracle	Architecture + debugging	Specialist; use for hard bugs and design questions
Librarian	Docs + code search	Read-heavy; good for research tasks
Explore	Fast grep/glob	Read-only; fastest for codebase exploration

---

oh-my-opencode.json Agent Configuration

Override which model each agent uses:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "sisyphus": {
      "model": "nvidia/qwen/qwen3.5-397b-a17b",
      "variant": "max"
    },
    "hephaestus": {
      "model": "nvidia/minimaxai/minimax-m2.1",
      "variant": "medium"
    },
    "oracle": {
      "model": "nvidia/qwen/qwen3-next-80b-a3b-thinking",
      "variant": "high"
    }
  },
  "categories": {
    "quick": {
      "model": "nvidia/qwen/qwen3-next-80b-a3b-instruct"
    }
  }
}

---

Running Agents from Claude Code (Background)

Use run_in_background: true on the Bash tool to launch agents without blocking:

npx oh-my-opencode run --agent hephaestus --directory /path/to/project \
  "$(cat /tmp/phase-prompt.txt)" > /tmp/phase-output.output 2>&1

Key observation: The npx oh-my-opencode run command:

1. Starts an opencode server on a port
2. Prints the session ID to stdout
3. Connects as client and streams events
4. Does NOT exit until all todos in the session are marked done

This means the process will run for as long as the agent is working. Monitor output with tail -f /tmp/output.file or check progress periodically.

---

Monitoring Progress

# Check line count (growing = agent still working)
wc -l /tmp/phase-output.output

# Tail last N lines
tail -80 /tmp/phase-output.output

# Check what sessions exist
opencode session list

# Export full session JSON (includes all tool calls)
opencode export <session-id>

The output file captures the full event stream including <think> blocks, tool call inputs/outputs, and the agent's final summary.

---

Pitfalls and Mistakes

❌ Pitfall 1: Using opencode run instead of npx oh-my-opencode run

# WRONG — stock opencode run exits after one model turn
opencode run --model nvidia/... "Implement feature"

# CORRECT — OMO run loops until all todos complete
npx oh-my-opencode run --agent hephaestus "Implement feature"

If the task is complex and requires multiple tool calls, opencode run may exit mid-task (when the model's response ends), while npx oh-my-opencode run keeps going.

---

❌ Pitfall 2: Thinking the session failed because the process exited early

The background process may complete quickly with exit code 0 but the session was cut off mid-execution. The session exits when:

• All todos are complete (success)
• The agent reaches its step limit
• The agent gets stuck and the server times out

Check the output file to distinguish — a cut-off session will have a tool call with "state": { "status": "pending" } at the end of the export.

Recovery: Resume with --session-id:

npx oh-my-opencode run --session-id ses_abc123 \
  "Continue where you left off. You created X but still need Y and Z."

---

❌ Pitfall 3: The minimax provider not available in opencode models

opencode models minimax
# Error: Provider not found: minimax

minimax-m2.1 is available through the nvidia provider:

nvidia/minimaxai/minimax-m2.1

Use this full path when specifying --model.

---

❌ Pitfall 4: Python-script approach for file creation/editing

Instructing agents to write Python scripts that use open(path, 'w').write(content) is slower and more error-prone than:

• New files: cat > /path/to/file <<'EOF' ... EOF in Bash
• Existing file modifications: Edit tool (read file first, then make targeted edit)

The Python approach adds an extra indirection layer where agents can go off-track writing the script itself instead of the target code.

---

Agent Behavior Observations

Hephaestus (minimax-m2.1):

• Reads the actual codebase extensively before making changes
• Corrects test expectations to match real implementation behavior
• Self-corrects Edit tool hash mismatches by re-reading and retrying
• Can go into reading loops on complex codebases — will eventually produce correct output
• Slower than qwen3-next but produces higher quality, codebase-aware changes

qwen3-next-80b-a3b-instruct:

• Faster execution, less codebase reading
• More prone to using outdated patterns if not given explicit correct examples
• Better with highly detailed prompts that specify exact API usage

For implementation tasks: Hephaestus with detailed prompt > qwen3-next with detailed prompt > either model with vague prompt

---

Prompt Best Practices for OMO Agents

1. Specify file operations approach: "Use cat > file <<'EOF' for new files, Edit tool for modifications"
2. Give exact API examples for any library with a tricky API (e.g., rmcp 0.10)
3. List steps explicitly — OMO tracks these as todos and won't exit until done
4. Reference specific file paths — agents orient faster with exact paths
5. Include verification step — always end with "Run cargo check and report final result" so the agent loops on errors