# 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](https://opencode.ai) 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](https://opencode.ai). The installer in Step 2 will check for it and guide you.

### Step 2 — Run the interactive installer

```bash
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.

```text
✔ 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:

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

```text
[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

| Requirement | Detail |
|---|---|
| **OpenCode** | The host application. Install separately from [opencode.ai](https://opencode.ai). |
| **Node.js** | v20 or newer (the CLI installer and Codex components require it). |
| **Bun** | Bundled into the prebuilt binaries; you do not need to install it separately for normal use. |
| **Operating system** | macOS (arm64/x64), Linux (x64/arm64, glibc or musl), and Windows (x64). Prebuilt binaries are shipped for each. |
| **A model subscription** | At least one of: Claude, OpenAI/ChatGPT, Gemini, GitHub Copilot, OpenCode Zen, Z.ai, Kimi, OpenCode Go, or Vercel AI Gateway. |

> [!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:

```bash
npx oh-my-opencode install
```

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

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

The available install flags are:

| Flag | Values | Meaning |
|---|---|---|
| `--no-tui` | — | Run non-interactively. Requires the other options to be set explicitly. |
| `--claude <value>` | `no`, `yes`, `max20` | Claude subscription tier. `max20` is the Claude Max 20× plan. |
| `--openai <value>` | `no`, `yes` | OpenAI / ChatGPT subscription. |
| `--gemini <value>` | `no`, `yes` | Google Gemini integration. |
| `--copilot <value>` | `no`, `yes` | GitHub Copilot subscription. |
| `--opencode-zen <value>` | `no`, `yes` | OpenCode Zen access. |
| `--zai-coding-plan <value>` | `no`, `yes` | Z.ai Coding Plan subscription. |
| `--kimi-for-coding <value>` | `no`, `yes` | Kimi For Coding (Moonshot) subscription. |
| `--opencode-go <value>` | `no`, `yes` | OpenCode Go subscription. |
| `--vercel-ai-gateway <value>` | `no`, `yes` | Vercel AI Gateway access. |
| `--skip-auth` | — | Skip authentication setup hints during install. |

> [!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:

```bash
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`:

```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`:

```bash
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:

```bash
omo doctor
```

```text
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](#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:

```bash
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.

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

Common options:

| Option | Description |
|---|---|
| `-a, --agent <name>` | Which agent to use. Defaults to your configured default, falling back to **Sisyphus**. |
| `-m, --model <provider/model>` | Override the model, e.g. `anthropic/claude-sonnet-4` or `openai/gpt-5.4`. |
| `-d, --directory <path>` | Working directory to run in (defaults to the current directory). |
| `-p, --port <port>` | Server port. Attaches to an existing server if the port is already in use. |
| `--attach <url>` | Attach to an already-running OpenCode server instead of starting one. |
| `--session-id <id>` | Resume an existing session instead of creating a new one. |
| `--on-complete <command>` | Shell command to run after the task finishes (e.g. send a notification). |
| `--json` | Emit a structured JSON result to stdout (ideal for scripting). |
| `--verbose` | Show the full event stream rather than just messages and tool calls. |
| `--no-timestamp` | Drop the timestamp prefix from output lines. |

**Examples**

Run a specific agent with a model override:

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

Capture a machine-readable result:

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

Resume a previous session and notify when done:

```bash
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

```bash
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.

```bash
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

| Agent | Role |
|---|---|
| **Sisyphus** | The default builder. A relentless, test-driven coding agent that implements features end-to-end. This is what you'll use most. |
| **Sisyphus Junior** | A lighter-weight builder used for delegated sub-tasks and parallel work. Keeps its own notepad of progress. |
| **Atlas** | The planner/orchestrator. Breaks large work into a plan ("boulder") and coordinates execution, including background and team work. |
| **Prometheus** | A focused agent constrained to Markdown-only output — used for planning documents and write-ups rather than code edits. |
| **Hephaestus** | A builder variant tuned for GPT-class models (the `no-hephaestus-non-gpt` hook keeps it on GPT models). |
| **Oracle** | A high-reasoning consultant for hard questions and design decisions. |
| **Librarian** | A research/retrieval agent for finding things across a codebase or docs. |
| **Explore** | A fast read-only exploration agent for surveying code without making changes. |
| **Multimodal Looker** | Handles images and visual input via the `look_at` tool (screenshots, diagrams, design mockups). |
| **Metis** | A reasoning-heavy advisor (mapped to the `ultrabrain` category by default in examples). |
| **Momus** | A reviewer/critic agent that re-reviews plans and work. |

> [!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:

| Category | Intended for |
|---|---|
| `ultrabrain` | The hardest reasoning and architecture work. |
| `deep` | Deep multi-step problem solving. |
| `visual-engineering` | Front-end / UI work that benefits from a vision-capable model. |
| `artistry` | Creative or design-leaning tasks. |
| `writing` | Documentation and prose. |
| `quick` | Fast, cheap, routine actions. |
| `unspecified-low` / `unspecified-high` | Fallback buckets for uncategorized work at low/high effort. |

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.

```text
ultrawork: migrate the entire codebase from CommonJS to ESM
```

Other keywords the detector recognizes:

| Keyword | Effect |
|---|---|
| `ultrawork` / `ulw` | Full orchestration mode — plan, delegate, verify. |
| `search` | Expand into a broad code/content search workflow. |
| `analyze` | Expand into a deeper analysis workflow. |
| `team` | Spin up **team mode** (multiple agents collaborating — see §5.4). |
| `hyperplan` | Produce a detailed plan before acting. |
| `hyperplan-ultrawork` | Combine deep planning with full orchestration. |

> [!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.

```bash
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.

```text
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:

```bash
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

| Tool | What it does |
|---|---|
| **`hashline_edit`** | Hash-anchored file editing. Instead of fragile line numbers, edits are anchored to a hash of the surrounding lines, so they stay correct even if the file shifts. Enable with `"hashline_edit": true`. |
| **`look_at`** | Opens and analyzes images (screenshots, diagrams, mockups) for vision-capable models. |
| **`read_image_resizer`** | Automatically resizes oversized images before they reach the model. |
| **`write_existing_file_guard`** | Prevents accidentally overwriting an existing file with `write` — you're told to use `edit` instead. |

### 6.2 Searching and navigating code

| Tool | What it does |
|---|---|
| **`grep`** | A fast, bundled ripgrep-based content search (downloads a ripgrep binary on first use). |
| **`glob`** | Fast filename/path matching. |
| **`ast-grep`** (MCP) | Structural, syntax-aware search and refactoring across many languages — find code by its shape, not just text. |
| **`lsp`** (MCP) | Language Server tools: diagnostics, go-to-definition, find-references, symbols, and safe rename. |

### 6.3 Sessions, tasks, and skills

| Tool | What it does |
|---|---|
| **`session_read` / `session_write` / `session_search`** | Persistent session memory the agent can read back and search. |
| **`task`** | Structured task/todo management for multi-step work. |
| **`delegate_task` / `background_task` / `call_omo_agent`** | Spawn and coordinate sub-agents (see §5.2). |
| **`skill` / `skill_mcp`** | Load a **skill** — a reusable, pre-written capability (see §7). |
| **`interactive_bash`** | Run an interactive shell session the agent can drive. |
| **`git_bash`** (MCP) | On Windows, routes git through a proper bash environment. |

> [!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:

| Skill | Purpose |
|---|---|
| `programming` | Language-specific best-practice references (Go, Python, Rust, TypeScript) and scaffolding. |
| `debugging` | Structured debugging methodology and runtime/tool references. |
| `refactor` | Safe, systematic refactoring. |
| `review-work` | Review a change for quality before it ships. |
| `start-work` | Begin a durable, planned unit of work (see §5.5). |
| `frontend-ui-ux` | Front-end and UI/UX guidance. |
| `git-master` | Git workflow assistance, including commit message conventions. |
| `security-research` / `security-review` | Security-focused analysis. |
| `remove-ai-slops` | Clean up tell-tale "AI-generated" artifacts from code and text. |
| `init-deep` | Deep project initialization / onboarding. |

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

```jsonc
{
  "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

```bash
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

```bash
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:

```text
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

```bash
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.

---

_Generated June 2026 from code-yeongyu/oh-my-openagent at 4a24c0c. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._