oh-my-opencode User Guide

oh-my-opencode (also published as oh-my-openagent, and invoked as omo) is a batteries-included plugin that turns OpenCode into a multi-model AI agent harness. It adds a cast of purpose-built coding agents, parallel background workers, hash-anchored editing, LSP/AST code tools, a keyword-driven "ultrawork" orchestration mode, team mode for multi-agent collaboration, and dozens of quality-of-life hooks — all installed with a single command.

The same engine also ships as LazyCodex, a plugin for OpenAI's Codex CLI. This guide covers everyday usage; deep architecture, the full configuration reference, and operations live in the companion Admin Guide.

Note

oh-my-opencode is a plugin, not a standalone model. It rides on top of OpenCode (or Codex) and your own model subscriptions (Claude, OpenAI, Gemini, GitHub Copilot, MiniMax, Kimi, Z.ai, and more). You bring the model access; oh-my-opencode makes the agent dramatically more capable.

1. Quick Start

Get from zero to a working agent in three steps.

Step 1 — Install OpenCode

oh-my-opencode is an OpenCode plugin, so you need OpenCode first. If you do not have it yet, install it from opencode.ai. The installer in Step 2 will check for it and guide you.

Step 2 — Run the interactive installer

npx oh-my-opencode install

This launches an interactive terminal UI (TUI) that:

• Detects your OpenCode (or Codex) installation.
• Asks which model subscriptions you have (Claude, OpenAI/ChatGPT, Gemini, GitHub Copilot, and others).
• Writes the plugin configuration and registers the bundled agents, tools, and MCP servers.

✔ Detected OpenCode
✔ Configured Claude (max20), OpenAI
✔ Registered agents: Sisyphus, Atlas, Prometheus, Hephaestus …
✔ oh-my-opencode is ready. Start OpenCode and pick the "Sisyphus" agent.

Tip

omo and oh-my-openagent are aliases for the same binary. npx omo install does exactly the same thing as npx oh-my-opencode install.

Step 3 — Start working

Open OpenCode in your project and select an agent (Sisyphus is the default builder). Or drive it headlessly from the shell:

omo run "Add input validation to the signup form and write tests"

[12:01:04] Sisyphus › Reading src/forms/signup.ts …
[12:01:22] Sisyphus › Editing src/forms/signup.ts (hashline_edit)
[12:01:48] Sisyphus › Running tests … 14 passed
✔ Done

That's it. The sections below explain everything you can do from here.

2. Installation

2.1 Requirements

Note

Platform binaries are delivered as optional npm dependencies (oh-my-opencode-darwin-arm64, oh-my-opencode-linux-x64, oh-my-opencode-windows-x64, and so on). Your package manager automatically picks the one matching your OS and CPU. "baseline" variants exist for older CPUs without AVX2.

2.2 Install for OpenCode

The interactive installer is the recommended path:

npx oh-my-opencode install

If you prefer a non-interactive install (for scripts or CI), pass --no-tui together with explicit subscription flags:

npx oh-my-opencode install --no-tui --claude max20 --openai yes

The available install flags are:

Tip

You can re-run omo install any time to add a new subscription or repair a broken setup. It is safe to run repeatedly.

2.3 Install for Codex (LazyCodex)

If you use OpenAI's Codex CLI instead of OpenCode, install the Codex flavor:

npx lazycodex-ai install

This builds and copies the plugin into the Codex plugin cache, registers the sisyphuslabs marketplace, installs runtime dependencies, and enables the relevant Codex features in your config.toml:

[features]
plugins = true
plugin_hooks = true

[plugins."omo@sisyphuslabs"]
enabled = true

To configure Codex with autonomous permissions during install (approval never, full filesystem access, network enabled), add --codex-autonomous:

npx lazycodex-ai install --codex-autonomous

Warning

--codex-autonomous removes Codex's approval prompts and grants broad filesystem and network access. Only enable it in environments you trust (for example, a disposable container or a dedicated project sandbox).

2.4 Verify your installation

Run the built-in doctor to confirm everything is wired correctly:

omo doctor

oh-my-opencode doctor
  ✔ OpenCode detected (v1.15.4)
  ✔ Config valid: ~/.config/opencode/oh-my-opencode.jsonc
  ✔ Agents registered: 11
  ✔ MCP servers reachable: ast-grep, git-bash, lsp
  ✔ Model resolution OK

For a compact one-line dashboard, use omo doctor --status. For machine-readable output, add --json. See Section 9, Troubleshooting when the doctor reports problems.

2.5 Uninstall and cleanup

To remove Codex project-local and home artifacts that oh-my-opencode created:

omo cleanup
omo cleanup --project /path/to/repo    # also clean a project's .codex/.omx artifacts
omo cleanup --json                     # structured output

3. Everyday Usage

There are two ways to drive oh-my-opencode: interactively inside OpenCode (pick an agent and chat) and headlessly from the shell with omo run. Most of this guide applies to both.

3.1 The run command

omo run executes a single agent task from the command line and prints the result. It is the workhorse for scripts, cron jobs, and "do this one thing" requests.

omo run "Refactor the auth module to use async/await"

Common options:

Examples

Run a specific agent with a model override:

omo run -a hephaestus -m openai/gpt-5.4 "Find and fix the flaky test in tests/api"

Capture a machine-readable result:

omo run --json "Summarize what changed in the last commit" > result.json

Resume a previous session and notify when done:

omo run --session-id ses_abc123 --on-complete "say done" "Continue the migration"

Tip

Set a default agent so you never have to pass -a. Add "default_run_agent": "sisyphus" to your oh-my-opencode.jsonc, or set the OPENCODE_DEFAULT_AGENT environment variable.

3.2 Checking versions and capabilities

omo version                       # print the installed version
omo get-local-version             # version resolved from this project's config
omo get-local-version --json      # same, machine-readable
omo refresh-model-capabilities    # refresh the model capability table from models.dev

refresh-model-capabilities pulls the latest model metadata (context window sizes, reasoning support, vision support) so agent routing and fallback decisions stay accurate as providers ship new models.

omo refresh-model-capabilities --source-url https://models.dev/api.json --json

4. The Agents

oh-my-opencode's headline feature is a roster of specialized agents, each tuned for a different kind of work and (optionally) a different model. You select an agent in the OpenCode TUI or with omo run -a <name>.

4.1 Agent roster

Note

OpenCode's own built-in build and plan agents remain available alongside these. oh-my-opencode can override their behavior through configuration (see the Admin Guide).

4.2 Picking the right agent

• Just build something → Sisyphus (default). It reads code, edits with precision, runs tests, and iterates.
• Plan a big change first → Atlas to plan, then let it delegate to builders.
• A tricky design question → Oracle or Metis for deeper reasoning.
• Look at a screenshot or diagram → Multimodal Looker (or just attach an image and let the agent route to it).
• Review work before merging → Momus.

4.3 Categories: model routing buckets

Rather than hard-coding a model per agent, oh-my-opencode groups work into categories, and each category maps to a model. This lets you assign your best model to your hardest work and a cheap, fast model to routine work — once — and have every agent honor it.

Built-in categories:

You assign models to categories in oh-my-opencode.jsonc. See the Admin Guide's configuration reference for the exact syntax; a typical setup routes ultrabrain to your strongest model and quick to a cheap one.

5. Power Features

This is where oh-my-opencode goes beyond a normal coding assistant.

5.1 Ultrawork — keyword-triggered orchestration

Type ultrawork (or ulw) anywhere in your message and oh-my-opencode injects an orchestration directive that makes the agent plan, parallelize, and verify its work much more aggressively. It is the single most impactful thing you can type.

ultrawork: migrate the entire codebase from CommonJS to ESM

Other keywords the detector recognizes:

Tip

If you want ultrawork on every session automatically, set "default_mode": { "ultrawork": true } in your config — no keyword required.

5.2 Background and delegated tasks

oh-my-opencode can run sub-agents in parallel in the background while the main agent keeps working. This is what makes large refactors and multi-file changes fast.

• delegate_task hands a self-contained sub-task to another agent (optionally a different model/category) and waits for or streams back the result.
• background_task launches work that runs concurrently; the parent is "woken" when a child finishes.
• call_omo_agent invokes a named agent for a focused request.

You don't usually call these tools by hand — the agents use them automatically when you ask for big, parallelizable work (especially under ultrawork). You'll see child tasks appear as they spawn and complete.

Note

A built-in circuit breaker caps how many tool calls a runaway sub-agent can make, so a confused background task can't burn unlimited tokens. Concurrency, depth, and timeouts are all configurable (Admin Guide).

5.3 Ralph Loop and ULW Loop — autonomous goal loops

For long-running, goal-directed work, oh-my-opencode offers two loop modes that keep the agent going until a goal is met or a limit is hit:

• Ralph Loop (/ralph-loop) — repeatedly re-prompts the agent to continue until the work is done or the iteration cap is reached. Cancel with /cancel-ralph.
• ULW Loop (/ulw-loop) — a durable, repo-native multi-goal loop with explicit success criteria and an evidence audit, so the agent must show that each goal was actually met.

omo ulw-loop --brief "Get the test suite to 100% pass and zero type errors"

Caution

Loop modes are autonomous — the agent will keep taking actions (including edits and commands) without pausing for you. Start with a bounded iteration count and review the result. The default Ralph Loop cap is 100 iterations.

5.4 Team Mode — multiple agents collaborating

Type team (or enable it in config) to run several agents at once as a coordinated team, communicating through a shared mailbox. A team lead coordinates members, each working in parallel.

When tmux visualization is enabled, each member gets its own tmux pane so you can watch them work side by side.

team: split the API rewrite across services — one agent per service

Team mode has sensible safety limits out of the box: up to 8 members (4 running in parallel), wall-clock and message budgets, and per-member turn caps. All are configurable.

Note

Team mode benefits from tmux being installed for the multi-pane visualization, but it is not required — members can run without panes.

5.5 Start-Work and Boulder — durable plans

The start-work flow (/start-work) creates a durable plan stored in .omo/boulder.json and an associated plan file under .omo/plans/. A "boulder" is a unit of tracked work with TODOs and verification steps. Continuation hooks make sure the agent keeps pushing the boulder uphill — if it stops with incomplete TODOs, it's nudged to continue.

Inspect active work at any time:

omo boulder                 # show boulder state for the current project
omo boulder -w <work-id>    # filter to one work item
omo boulder --json

5.6 Remote control with OpenClaw (Discord / Telegram)

OpenClaw lets you receive notifications and send replies to a running agent from Discord or Telegram — useful for kicking off or steering long jobs from your phone. It is disabled by default and enabled through the openclaw config block (Admin Guide).

6. The Tools Your Agents Use

oh-my-opencode adds a set of high-quality tools on top of OpenCode's built-ins. You rarely invoke these directly, but knowing what they are helps you understand what the agent is doing and write better requests.

6.1 Editing and reading

6.2 Searching and navigating code

6.3 Sessions, tasks, and skills

Tip

If your model provider limits the number of tools (for example, OpenAI's 128-tool cap), set experimental.max_tools in your config. oh-my-opencode will keep the highest-priority tools and drop the rest to stay under the limit.

7. Skills

Skills are reusable, self-contained capabilities the agent can load on demand — think of them as expert playbooks. oh-my-opencode bundles a library of them and lets you add your own.

Bundled skill highlights:

Add your own skills by pointing the config at a directory of SKILL.md files:

{
  "skills": {
    "sources": [{ "path": "skill/", "recursive": true }]
  }
}

You can also enable or disable individual skills (disabled_skills) — see the Admin Guide.

8. Common Tasks (Recipes)

8.1 Do a big refactor fast

omo run "ultrawork: convert all class components in src/ to function components with hooks"

The ultrawork keyword triggers planning, parallel delegation, and verification automatically.

8.2 Fix a failing test suite end-to-end

omo ulw-loop --brief "Make the full test suite pass with zero type errors. Show evidence."

The ULW loop keeps iterating and must produce evidence each goal is met before it stops.

8.3 Review a change before merging

In OpenCode, switch to the Momus agent (or invoke the review-work skill) and ask it to review your working tree or a specific diff.

8.4 Work from a screenshot

Attach an image and describe what you want. The Multimodal Looker agent / look_at tool reads the image:

Here's a screenshot of the bug. ultrawork: reproduce and fix it.

8.5 Use different models for different work

In oh-my-opencode.jsonc, assign your strongest model to ultrabrain and a fast one to quick. Every agent then routes hard work to the strong model and routine work to the cheap one — no per-request flags needed.

8.6 Run headless in CI

omo run --no-timestamp --json -a sisyphus "Apply the codemod in scripts/codemod.ts and commit" \
  | tee result.json

8.7 Steer a long job from your phone

Enable OpenClaw with your Discord or Telegram credentials (Admin Guide), start a long ulw-loop, and reply from chat to nudge the agent.

9. Troubleshooting

Format: each entry gives the symptom, the likely cause, and the fix.

Error: Model string must be in <provider>/<model> format

Cause: A -m/--model value (or a config model field) is missing the provider prefix. Solution: Always include the provider, e.g. anthropic/claude-sonnet-4, not just claude-sonnet-4. Prevention: Use the exact provider/model ids your provider exposes; run omo doctor to validate model resolution.

Error: Provider cannot be empty / Model ID cannot be empty

Cause: A model string like /gpt-5.4 or openai/ — one half is blank. Solution: Supply both halves: openai/gpt-5.4.

Model routing is ignored after restart, falling back to a default model

Cause: A known issue where oh-my-opencode.json model routing can be dropped on restart (community issue #3570). Solution: Re-run omo doctor to confirm your config is valid and loaded, and verify the config file is in the active OpenCode config directory. Explicitly set the category models rather than relying on per-agent model (which is deprecated in favor of category).

An agent (Atlas / Quick) stops unexpectedly mid-plan

Cause: Some models (notably certain MiniMax variants) are flagged "unstable" and can halt during plan execution (community issue #3198). oh-my-opencode runs unstable agents in a monitored background mode for exactly this reason. Solution: Route that agent/category to a more stable model, or rely on the babysitter and runtime-fallback features to recover. See runtime_fallback in the Admin Guide.

Error: Port must be between 1 and 65535 / No available port found in range

Cause: An invalid -p/--port value, or every candidate port is occupied. Solution: Pass a valid free port, or omit --port and let oh-my-opencode pick one. Use --attach <url> to connect to a server you already have running.

Error: Session not found: <id> / Failed to create session after all retries

Cause: The --session-id you resumed no longer exists, or the OpenCode server is unreachable. Solution: Start a fresh session (omit --session-id), or confirm the server is running and reachable at the expected port/URL.

Error: File already exists. Use edit tool instead.

Cause: The agent tried to write over an existing file; the write-existing-file-guard blocked it. Solution: This is protective and expected — let the agent use edit/hashline_edit to modify the file instead of overwriting it.

Error: ripgrep binary not found after extraction / Unsupported platform

Cause: The bundled grep tool failed to download or extract its ripgrep binary, or you're on an unsupported platform. Solution: Check your network/proxy, ensure your platform is one of the supported targets, and retry. The agent can fall back to OpenCode's built-in search.

Error: Agent task timed out after 5 minutes. / Prompt was not durably accepted by OpenCode

Cause: A delegated/background sub-agent took too long or the OpenCode server didn't acknowledge the prompt. Solution: Break the task into smaller pieces, raise the relevant background-task timeout in config, or check server health with omo doctor.

Team errors: team_create denied … / <tool> is lead-only

Cause: A team-mode rule was violated — e.g. a member tried a lead-only action, or a session tried to join two teams. Solution: Only the team lead performs lead-only actions; members operate within their assignment. Start a fresh team if a session is already a participant elsewhere.

MiniMax / new model not appearing in the model list

Cause: The model capability table is stale, or the provider prefix isn't recognized yet (community issues #4692, #3535). Solution: Run omo refresh-model-capabilities, then restart OpenCode. Confirm the provider is configured.

Builtin skills (init-deep, review-work, start-work) not showing as slash commands

Cause: A known visibility issue on some OpenCode Desktop builds (community issue #4714). Solution: Update to the latest oh-my-opencode and OpenCode, re-run omo install, and restart. Verify with omo doctor.

omo doctor reports an invalid config

Cause: A typo or out-of-range value in oh-my-opencode.jsonc (the config is strictly validated). Solution: Run omo doctor --verbose to see the exact field and expected values, then fix it. Reference the Admin Guide's configuration table for valid ranges and defaults.

10. Frequently Asked Questions

Q: Is oh-my-opencode a model or an AI provider? No. It's a plugin that supercharges OpenCode (or Codex). You connect your own model subscriptions; oh-my-opencode adds agents, tools, and orchestration on top.

Q: What's the difference between oh-my-opencode, oh-my-openagent, omo, and lazycodex? They're the same project. oh-my-opencode/oh-my-openagent/omo are interchangeable command names for the OpenCode plugin. lazycodex/lazycodex-ai install the Codex flavor of the same engine.

Q: Do I have to use the keyword ultrawork? No, but it's the easiest way to get the agent's best work on a per-message basis. You can also turn it on for every session with default_mode.ultrawork.

Q: Which agent should I start with? Sisyphus — it's the default, all-purpose test-driven builder.

Q: Can I use multiple model providers at once? Yes. That's a core feature. Assign different providers/models to different categories and agents, and oh-my-opencode routes work accordingly, with automatic fallback if a provider errors.

Q: What happens if my model provider returns an error mid-task? With runtime_fallback enabled, oh-my-opencode automatically retries on a fallback model for errors like rate limits (429) and server errors (5xx), with a cooldown before retrying the failed model.

Q: How do I make edits more reliable on large files? Enable hashline_edit ("hashline_edit": true). It anchors edits to content hashes instead of line numbers, so they survive file shifts.

Q: Is my code or prompt sent anywhere? oh-my-opencode sends an anonymous, daily "active install" event to PostHog by default — no prompts, file contents, or hostnames. Opt out by setting OMO_DISABLE_POSTHOG=1 (and OMO_SEND_ANONYMOUS_TELEMETRY=0). The bundled LSP, rules, and comment-checker components run locally and make no network calls of their own.

Q: How do I disable a feature I don't want (a hook, agent, MCP, skill, or command)? Use the disabled_hooks, disabled_agents, disabled_mcps, disabled_skills, or disabled_commands arrays in your config. See the Admin Guide.

Q: Can it run unattended for a long time? Yes — use Ralph Loop or ULW Loop for autonomous, goal-directed runs with iteration caps and (for ULW) evidence requirements. Review the output; these modes act without pausing.

Q: Does it work on Windows? Yes. Windows x64 binaries are shipped, and a bundled git_bash MCP routes git through a proper bash environment on Windows.

Q: Where is my configuration stored? In oh-my-opencode.jsonc (or .json) in your OpenCode config directory, and/or per-project under .opencode/. The full schema is documented in the Admin Guide.

Q: How do I get more detail when something breaks? Run omo doctor --verbose. For specific components, several support debug env vars (for example COMMENT_CHECKER_DEBUG, NODE_DEBUG=codex-rules).

Q: The agent keeps trying to "continue" after I want it to stop. Why? Continuation hooks (todo-continuation, start-work continuation, Ralph Loop) intentionally nudge the agent to finish incomplete work. Cancel loops with /cancel-ralph, or complete/clear the active boulder.