oh-my-opencode/docs/guide/installation.md

Installation

oh-my-openagent ships in two editions of the same product:

• Ultimate Edition (omo for OpenCode) — the full omo experience. 11 discipline agents, 54+ lifecycle hooks, all built-in MCPs, every slash command, Team Mode, ulw-loop, hashline edits, the works.
• Light Edition (omo for OpenAI Codex CLI) — the 5 components that port cleanly to Codex's plugin system: rules, comment-checker, lsp, ultrawork, ulw-loop. No agent orchestration, no team_* tools, no built-in web/docs/code search MCPs — Codex CLI's native surface does that work.

Most users want Ultimate. Pick Light if you are already invested in Codex CLI. Pick both if you want OMO available wherever you happen to be working that day.

You want	Run	Lands on disk
Ultimate (OpenCode)	bunx omo install (TUI walks you through it)	Plugin registered in opencode.json, agent/model config, provider auth
Light (Codex CLI)	bunx omo install --platform=codex or bunx lazycodex install (no questions)	~/.codex/plugins/cache/sisyphuslabs/omo/, ~/.codex/config.toml marketplace/plugin blocks, ~/.local/bin/omo-*
Both	bunx omo install --platform=both	Both of the above

--platform defaults to opencode (Ultimate). The bunx lazycodex install alias is a shortcut for bunx omo install --platform=codex: same compiled CLI, different default. lazycodex is a repo/npm/bin alias, not the Codex marketplace name.

For Humans

Strongly recommended: let an LLM agent install Ultimate for you. Ultimate setup involves subscription detection, model selection across 11 agents, provider authentication, and config migration — humans fat-finger these. An LLM agent reads the full guide and walks every step correctly.

Ultimate (OpenCode) — let an agent do it

Paste this prompt into Claude Code, AmpCode, Cursor, or any LLM agent session:

Install and configure oh-my-openagent by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

Light (Codex CLI) — one line, no agent needed

The Light edition installer asks zero questions, so a human can run it directly:

bunx omo install --platform=codex
# equivalent:
bunx lazycodex install

It writes only to ~/.codex/. No OpenCode interaction, no provider flags. Codex config will register marketplace sisyphuslabs from https://github.com/code-yeongyu/lazycodex.git and enable plugin omo@sisyphuslabs.

A note on direct install

If you insist on running the Ultimate installer yourself:

bunx oh-my-openagent install

The TUI walks you through it. Do NOT use npm install -g, bun add -g, or bun install -g — global installation is not officially supported. oh-my-openagent is a plugin that must resolve from where OpenCode/Codex loads plugins, and the prepare script requires Bun. Always invoke via bunx.

For LLM Agents

IMPORTANT: Use curl to fetch this file, NOT WebFetch. WebFetch summarizes content and loses critical flags like --platform, subscription questions, and Codex verification details. Always use:

curl -fsSL https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

If you are an LLM Agent helping a user install oh-my-openagent, welcome. You will help your user install the harness, verify the setup, and configure model providers. Tell user this with greetings, with text oMoMoMoMo....

Follow these steps in order.

Step 0: Ask user which platform(s) and subscriptions

First, ask which platform(s) they want to install for. This determines the rest of the flow:

"Which harness do you want to install oh-my-openagent for? Pick one:

1. OpenCode — terminal AI coding agent
2. OpenAI Codex CLI
3. Both"

Map their answer to the --platform flag:

User says	Use
OpenCode	--platform=opencode (this is also the default if omitted)
Codex	--platform=codex
Both	--platform=both

If the user picked Codex only, skip the rest of Step 0 — Codex needs no subscription questions. Go straight to Step 2.

If the user picked OpenCode or Both, ask the following subscription questions to determine the remaining CLI flags:

1. Do you have a Claude Pro/Max Subscription?

   • yes + max20 mode (20×) → --claude=max20
   • yes but not max20 → --claude=yes
   • no → --claude=no

2. Do you have an OpenAI/ChatGPT Plus Subscription?

   • yes → --openai=yes (enables GPT-5.5 for Oracle and Hephaestus)
   • no → --openai=no (default)

3. Will you integrate Gemini models?

   • yes → --gemini=yes
   • no → --gemini=no

4. Do you have a GitHub Copilot Subscription?

   • yes → --copilot=yes
   • no → --copilot=no

5. Do you have access to OpenCode Zen (opencode/ models)?

   • yes → --opencode-zen=yes
   • no → --opencode-zen=no (default)

6. Do you have a Z.ai Coding Plan subscription?

   • yes → --zai-coding-plan=yes
   • no → --zai-coding-plan=no (default)

7. Do you have an OpenCode Go subscription? ($10/month for GLM-5/5.1, Kimi K2.5/K2.6, MiniMax M2.7)

   • yes → --opencode-go=yes
   • no → --opencode-go=no (default)

8. Do you have a Kimi for Coding subscription?

   • yes → --kimi-for-coding=yes
   • no → --kimi-for-coding=no (default)

9. Do you use Vercel AI Gateway?

   • yes → --vercel-ai-gateway=yes
   • no → --vercel-ai-gateway=no (default)

Provider selection is agent-specific. There is no single global provider priority — each of the 11 agents has its own fallback chain.

MUST STRONGLY WARN, WHEN USER SAID THEY DON'T HAVE CLAUDE SUBSCRIPTION, SISYPHUS AGENT MIGHT NOT WORK IDEALLY.

Step 1: Prerequisites

For platform opencode or both

Check OpenCode is installed and on a supported version:

if command -v opencode &> /dev/null; then
    echo "OpenCode $(opencode --version) is installed"
else
    echo "OpenCode is not installed. Install it first."
    echo "Ref: https://opencode.ai/docs"
fi

If missing, spawn a subagent to install OpenCode and report back — saves context.

Required: OpenCode >= 1.0.150.

For platform codex or both

Check Codex CLI is installed:

if command -v codex &> /dev/null; then
    codex --version
else
    echo "Codex CLI is not installed. Install it first."
    echo "Ref: https://github.com/openai/codex"
fi

The installer expects ~/.codex/ to be writable. Codex CLI's first run creates this directory; if it does not exist yet, install Codex CLI and run it once before continuing.

Step 2: Run the installer

Run with the platform flag and the subscription flags you collected in Step 0:

bunx oh-my-openagent install \
  --no-tui \
  --platform=<opencode|codex|both> \
  [--claude=<yes|no|max20>] \
  [--gemini=<yes|no>] \
  [--copilot=<yes|no>] \
  [--openai=<yes|no>] \
  [--opencode-zen=<yes|no>] \
  [--zai-coding-plan=<yes|no>] \
  [--opencode-go=<yes|no>] \
  [--kimi-for-coding=<yes|no>] \
  [--vercel-ai-gateway=<yes|no>] \
  [--skip-auth]

--platform defaults to opencode if omitted. Subscription flags only apply when --platform is opencode or both. They are rejected under --platform=codex because the Light edition does not write OpenCode model config.

Examples:

• OpenCode + Claude Max20 + ChatGPT + Gemini:

  bunx oh-my-openagent install --no-tui --platform=opencode --claude=max20 --openai=yes --gemini=yes --copilot=no
  

• Codex only (no questions needed):

  bunx oh-my-openagent install --no-tui --platform=codex
  # equivalent:
  bunx lazycodex install --no-tui
  

• Both harnesses with Claude only:

  bunx oh-my-openagent install --no-tui --platform=both --claude=yes --gemini=no --copilot=no
  

• OpenCode + Z.ai for Librarian:

  bunx oh-my-openagent install --no-tui --platform=opencode --claude=yes --gemini=no --copilot=no --zai-coding-plan=yes
  

• OpenCode Go subscriber, nothing else:

  bunx oh-my-openagent install --no-tui --platform=opencode --claude=no --openai=no --gemini=no --copilot=no --opencode-go=yes
  

About the lazycodex bin name. lazycodex is an alias for the same compiled CLI and the Git repository that hosts the marketplace bundle. The only CLI difference is that lazycodex install defaults --platform=codex instead of opencode. You can still pass --platform=both to override. The Codex marketplace name is sisyphuslabs, and the plugin name is omo.

What the installer does:

Platform	Writes
opencode, both	Registers "oh-my-openagent" in opencode.json plugin array. Generates agent → model mappings into ~/.config/opencode/oh-my-openagent.jsonc.
codex, both	Copies packages/omo-codex/plugin/ into ~/.codex/plugins/cache/sisyphuslabs/omo/<version>/. Runs npm install + npm run build inside. Symlinks ~/.local/bin/omo-* (or $CODEX_LOCAL_BIN_DIR/omo-*) for each of the 5 components. Computes SHA256 trusted-hashes for every hook and writes [marketplaces.sisyphuslabs] with git source https://github.com/code-yeongyu/lazycodex.git, [plugins."omo@sisyphuslabs"], and [hooks.state."omo@sisyphuslabs:..."] blocks into ~/.codex/config.toml.

Both halves are independent and idempotent — re-running is safe.

Step 3: Verify

Verify OpenCode plugin (skip if platform=codex)

opencode --version  # Should be 1.0.150 or higher
cat ~/.config/opencode/opencode.json
# Plugin array should contain "oh-my-openagent" (legacy "oh-my-opencode" still loads with a warning)
bunx oh-my-openagent doctor

doctor runs six categories of checks: System (binary version, plugin registration), Config (JSONC + Zod schema), TUI Plugin, Tools (AST-grep, LSP, GitHub CLI, comment-checker), Models (cache, per-agent resolution, fallback chain availability), and Team Mode (if enabled). Exit code: 0 = ok, 1 = errors, 2 = warnings only.

Verify Codex CLI Light edition (skip if platform=opencode)

# Plugin cache present?
ls ~/.codex/plugins/cache/sisyphuslabs/omo/

# Marketplace source is the lazycodex repo?
grep -A4 'marketplaces.sisyphuslabs' ~/.codex/config.toml

# Codex config has the plugin block?
grep -A2 'omo@sisyphuslabs' ~/.codex/config.toml

# Component binaries linked?
ls ~/.local/bin/ | grep -E 'omo-(rules|comment-checker|lsp|ultrawork|ulw-loop)'

# Codex CLI sees the plugin?
codex --help

If any of these come back empty, re-run bunx omo install --platform=codex — the installer is idempotent and will recompute hook trust hashes.

Step 4: Configure authentication

Codex CLI

Codex uses its own OpenAI authentication. The Light edition inherits whatever auth Codex CLI is already using. There is nothing extra to configure here. If codex --help works for you, you are done with Codex auth.

OpenCode providers

Skip this section if --platform=codex. Otherwise, configure the providers the user said yes to in Step 0. Use an interactive terminal (tmux is fine) for the OAuth flows.

Anthropic (Claude)

opencode auth login
# Interactive Terminal: find Provider → select Anthropic
# Interactive Terminal: find Login method → select Claude Pro/Max
# Guide user through OAuth flow in browser
# Wait for completion
# Verify success and confirm with user

Google Gemini (Antigravity OAuth)

First, add the opencode-antigravity-auth plugin entry to opencode.json:

{
  "plugin": ["oh-my-openagent", "opencode-antigravity-auth@latest"]
}

Then merge the full model configuration from the opencode-antigravity-auth README into opencode.json. The plugin uses a variant system — models like antigravity-gemini-3-pro support low/high variants instead of separate -low/-high entries.

Override the agent models in your plugin config file (oh-my-openagent.jsonc or legacy oh-my-opencode.jsonc):

{
  "agents": {
    "multimodal-looker": { "model": "google/antigravity-gemini-3-flash" }
  }
}

Available Antigravity models: google/antigravity-gemini-3-pro (variants: low, high), google/antigravity-gemini-3-flash (variants: minimal, low, medium, high), google/antigravity-claude-sonnet-4-6, google/antigravity-claude-sonnet-4-6-thinking (variants: low, max), google/antigravity-claude-opus-4-5-thinking (variants: low, max).

Available Gemini CLI models: google/gemini-2.5-flash, google/gemini-2.5-pro, google/gemini-3-flash-preview, google/gemini-3.1-pro-preview.

Legacy tier-suffixed names like google/antigravity-gemini-3-pro-high still work but variants are recommended. Use --variant=high with the base model name instead.

Then authenticate:

opencode auth login
# Interactive Terminal: Provider → Google
# Interactive Terminal: Login method → OAuth with Google (Antigravity)
# Complete sign-in in browser (auto-detected)
# Optional: Add more Google accounts for multi-account load balancing

The plugin supports up to 10 Google accounts. When one account hits rate limits, it automatically switches to the next available account.

GitHub Copilot (Fallback Provider)

GitHub Copilot is supported as a fallback provider when native providers are unavailable. Priority is agent-specific. Common install-time defaults when Copilot is the best available provider:

Agent	Model
Sisyphus	github-copilot/claude-opus-4.7
Oracle	github-copilot/gpt-5.5
Explore	github-copilot/grok-code-fast-1
Atlas	github-copilot/claude-sonnet-4.6

Copilot acts as a proxy provider, routing requests to underlying models based on your subscription. Some agents (like Librarian) are not installed from Copilot alone and instead rely on other providers or runtime fallback.

Z.ai Coding Plan

Z.ai Coding Plan now mainly contributes glm-5 / glm-4.6v fallback entries. It is no longer the universal fallback for every agent.

When Z.ai is the primary provider, the most important fallbacks are:

Agent	Model
Sisyphus	zai-coding-plan/glm-5
visual-engineering	zai-coding-plan/glm-5
unspecified-high	zai-coding-plan/glm-5
Multimodal-Looker	zai-coding-plan/glm-4.6v

OpenCode Zen

OpenCode Zen provides access to opencode/ prefixed models including opencode/claude-opus-4-7, opencode/gpt-5.5, opencode/gpt-5.3-codex, opencode/gpt-5-nano, opencode/glm-5, opencode/big-pickle, opencode/minimax-m2.7, and opencode/minimax-m2.7-highspeed.

When OpenCode Zen is the best available provider, common examples:

Agent	Model
Sisyphus	opencode/claude-opus-4-7
Oracle	opencode/gpt-5.5
Explore	opencode/minimax-m2.7

Run the installer with --opencode-zen=yes and select "Yes" for OpenCode Zen at the prompt. If your OpenCode environment prompts for provider authentication, follow the OpenCode provider flow for opencode/ models.

Step 5: Understand your model setup

Model families

Not all models behave the same way. Understanding "similar" families helps you make safe substitutions.

Claude-like Models (instruction-following, structured output):

Model	Provider(s)	Notes
Claude Opus 4.7	anthropic, github-copilot, opencode	Best overall. Default for Sisyphus.
Claude Sonnet 4.6	anthropic, github-copilot, opencode	Faster, cheaper. Good balance.
Claude Haiku 4.5	anthropic, opencode	Fast and cheap. Good for quick tasks.
Kimi K2.6	opencode-go, vercel	Current default fallback after Claude Opus in primary Sisyphus chain. Claude-like behavior.
Kimi K2.5	kimi-for-coding, opencode, moonshotai, moonshotai-cn, firmware, ollama-cloud, aihubmix	Claude-like, available on multiple providers, still in active fallback chains.
Kimi K2.5 Free	opencode	Free-tier Kimi. Rate-limited but functional.
GLM 5.1	opencode-go, vercel	Claude-like behavior. Upgraded from GLM-5 on opencode-go.
GLM 5	zai-coding-plan, opencode	Claude-like behavior. Good for broad tasks.
Big Pickle (GLM 4.6)	opencode	Free-tier GLM. Decent fallback.

GPT Models (explicit reasoning, principle-driven):

Model	Provider(s)	Notes
GPT-5.3-codex	openai, github-copilot, opencode	Deep coding powerhouse. Available for deep category and explicit overrides.
GPT-5.5	openai, github-copilot, opencode	High intelligence. Default for Oracle, Hephaestus, and deep GPT-native fallbacks.
GPT-5.4 Mini	openai, github-copilot, opencode	Fast + strong reasoning. Default for quick category.
GPT-5-Nano	opencode	Ultra-cheap, fast. Good for simple utility tasks.

Different-behavior Models:

Model	Provider(s)	Notes
Gemini 3.1 Pro	google, github-copilot, opencode	Excels at visual/frontend tasks. Different reasoning style.
Gemini 3 Flash	google, github-copilot, opencode	Fast, good for doc search and light tasks.
MiniMax M2.7	opencode-go, opencode, vercel	Fast and smart. Utility fallback for various chains.
MiniMax M2.7 Highspeed	vercel, opencode	Faster utility variant used in Explore and retrieval chains.
Qwen 3.5 Plus	opencode-go	1M context, high-speed reasoning. Default for Explore and Librarian when GPT-5.4 Mini Fast is unavailable.

Speed-Focused Models:

Model	Provider(s)	Speed	Notes
Grok Code Fast 1	github-copilot, xai	Very fast	Optimized for code grep/search. Default for Explore.
Claude Haiku 4.5	anthropic, opencode	Fast	Good balance of speed and intelligence.
MiniMax M2.7 Highspeed	vercel, opencode	Very fast	High-speed MiniMax utility fallback used by runtime chains.
GPT-5.3-codex-spark	openai	Extremely fast	Blazing but compacts too aggressively. Not recommended for omo agents.

What each agent does and which model it got

Claude-Optimized Agents (prompts tuned for Claude-family models):

Agent	Role	Default Chain
Sisyphus	Main ultraworker	anthropic|github-copilot|opencode/claude-opus-4-7 (max) → opencode-go/kimi-k2.6 → kimi-for-coding/k2p5 → opencode|moonshotai|moonshotai-cn|firmware|ollama-cloud|aihubmix/kimi-k2.5 → openai|github-copilot|opencode/gpt-5.5 (medium) → zai-coding-plan|opencode/glm-5 → opencode/big-pickle
Metis	Plan review	anthropic|github-copilot|opencode/claude-sonnet-4-6 → anthropic|github-copilot|opencode/claude-opus-4-7 (max) → openai|github-copilot|opencode/gpt-5.5 (high) → opencode-go/glm-5.1 → kimi-for-coding/k2p5

Dual-Prompt Agents (auto-switch between Claude and GPT prompts at runtime via isGptModel()):

Priority: Claude > GPT > Claude-like models

Agent	Role	Default Chain	GPT Prompt?
Prometheus	Strategic planner	anthropic|github-copilot|opencode/claude-opus-4-7 (max) → openai|github-copilot|opencode/gpt-5.5 (high) → opencode-go/glm-5.1 → google|github-copilot|opencode/gemini-3.1-pro	Yes — XML-tagged, principle-driven (~300 lines vs ~1,100 Claude)
Atlas	Todo orchestrator	anthropic|github-copilot|opencode/claude-sonnet-4-6 → opencode-go/kimi-k2.6 → openai|github-copilot|opencode/gpt-5.5 (medium) → opencode-go/minimax-m2.7	Yes — GPT-optimized todo management

GPT-Native Agents (built for GPT, don't override to Claude):

Agent	Role	Default Chain	Notes
Hephaestus	Deep autonomous worker	GPT-5.5 (medium) only	"Codex on steroids." No fallback. Requires GPT access.
Oracle	Architecture/debugging	openai|github-copilot|opencode/gpt-5.5 (high) → google|github-copilot|opencode/gemini-3.1-pro (high) → anthropic|github-copilot|opencode/claude-opus-4-7 (max) → opencode-go/glm-5.1	High-IQ strategic backup. GPT preferred.
Momus	High-accuracy reviewer	openai|github-copilot|opencode/gpt-5.5 (xhigh) → anthropic|github-copilot|opencode/claude-opus-4-7 (max) → google|github-copilot|opencode/gemini-3.1-pro (high) → opencode-go/glm-5.1	Verification agent. GPT preferred.

Utility Agents (speed over intelligence — do not "upgrade" them):

Agent	Role	Default Chain
Explore	Fast codebase grep	openai/gpt-5.4-mini-fast → opencode-go/qwen3.5-plus → vercel/minimax-m2.7-highspeed → opencode-go|vercel/minimax-m2.7 → anthropic|opencode|vercel/claude-haiku-4-5 → openai|opencode|vercel/gpt-5.4-nano
Librarian	Docs/code search	(same chain as Explore)
Multimodal Looker	Vision/screenshots	openai|opencode/gpt-5.5 (medium) → opencode-go/kimi-k2.6 → zai-coding-plan/glm-4.6v → openai|github-copilot|opencode/gpt-5-nano

Why different models need different prompts

• Claude models respond well to mechanics-driven prompts — detailed checklists, templates, step-by-step procedures. More rules = more compliance.
• GPT models (especially 5.2+) respond better to principle-driven prompts — concise principles, XML-tagged structure, explicit decision criteria. More rules = more contradiction surface = more drift.

Key insight from Codex Plan Mode analysis: Codex Plan Mode achieves the same results with 3 principles in ~121 lines that Prometheus's Claude prompt needs ~1,100 lines across 7 files. The core concept is "Decision Complete" — a plan must leave ZERO decisions to the implementer. GPT follows this literally when stated as a principle; Claude needs enforcement mechanisms.

This is why Prometheus and Atlas ship separate prompts per model family — they auto-detect and switch at runtime.

Custom model configuration

If the user wants to override which model an agent uses, edit the plugin config file (oh-my-openagent.jsonc or legacy oh-my-opencode.jsonc):

{
  "agents": {
    "sisyphus": { "model": "kimi-for-coding/k2p5" },
    "prometheus": { "model": "openai/gpt-5.5" }, // Auto-switches to the GPT prompt
  },
}

Safe overrides (same family): Sisyphus Opus → Sonnet/Kimi K2.6/GLM 5; Prometheus Opus → GPT-5.5 (auto-switch); Atlas Kimi K2.6 → Sonnet/GPT-5.5 (auto-switch).

Dangerous overrides (no prompt support): Sisyphus → older GPT models (only 5.4/5.5 have dedicated GPT paths); Hephaestus → Claude (built for Codex); Explore → Opus (massive cost waste); Librarian → Opus (same).

Provider resolution

There is no single global provider priority. The installer and runtime resolve each agent against its own fallback chain, so the winning provider depends on the agent and the subscriptions enabled.

Step 6: First use — modes, commands, agents, skills

After install, the user interacts with oh-my-openagent through five surfaces. Walk them through each.

Modes (typed naturally in chat)

Just type one of these words in your message and the system injects the corresponding mode prompt:

Keyword	Editions	What it does
ultrawork or ulw	Both	Full orchestration mode — every agent (Ultimate) or the Codex ultrawork component (Light) activates, doesn't stop until done
search	Ultimate	Web/doc search focus
analyze	Ultimate	Deep analysis mode
team	Ultimate	Forces team_* tools orchestration (requires team_mode.enabled)
hyperplan	Ultimate	Adversarial planning via 5 hostile critics
hyperplan ultrawork (combo)	Ultimate	Both at once

Slash commands

All built-in slash commands are Ultimate-only — Codex CLI does not have a slash-command surface, so the Light edition omits this entire layer.

Command	Editions	Purpose
/init-deep	Ultimate	Auto-generate hierarchical AGENTS.md files throughout the project
/start-work	Ultimate	Spawn Prometheus to interview the user and build a plan, then execute
/ralph-loop	Ultimate	Self-referential dev loop until 100% done
/ulw-loop	Ultimate	Ultrawork-mode variant of the loop
/cancel-ralph	Ultimate	Stop an active Ralph loop
/stop-continuation	Ultimate	Stop ralph loop + todo continuation + boulder
/refactor	Ultimate	LSP + AST-grep + TDD-verified intelligent refactor
/handoff	Ultimate	Generate detailed context summary to continue in a new session
/remove-ai-slops	Ultimate	Strip AI-generated code smells from recent changes
/hyperplan	Ultimate	Direct invocation of hyperplan skill

Agents (11) — Ultimate only

All 11 discipline agents are part of the Ultimate edition. The Light edition does not ship agent orchestration — Codex CLI's own model selection takes that role. Sisyphus delegates to these; you don't usually call them directly, but knowing the cast helps:

• Sisyphus — main orchestrator. Plans, delegates, drives to completion.
• Hephaestus — "Codex on steroids." Deep autonomous worker, GPT-native.
• Prometheus — strategic planner, interviews you before code is written.
• Atlas — todo-list orchestrator.
• Oracle — architecture/debugging consultant.
• Librarian — external docs/code search.
• Explore — fast codebase grep.
• Multimodal-Looker — vision/PDF analysis.
• Metis — pre-planning consultant, reviews Prometheus plans for gaps.
• Momus — high-accuracy plan reviewer.
• Sisyphus-Junior — category-spawned executor for delegated tasks.

Skills

Built-in skills load automatically when their description matches your task. The user does not need to invoke them by name. The OpenCode skill system is Ultimate-only; the Light edition does not have a skill loader.

Skill	Editions	When it triggers
playwright	Ultimate	Browser automation
git-master	Ultimate	Atomic commits, rebases, history search
frontend-ui-ux	Ultimate	UI/UX implementation work
review-work	Ultimate	Post-implementation code review
ai-slop-remover	Ultimate	Cleaning AI-generated code smells
team-mode	Ultimate	Loaded only when team_mode.enabled

Add custom skills under .opencode/skills/<name>/SKILL.md (project scope) or ~/.config/opencode/skills/<name>/SKILL.md (user scope). Each SKILL.md declares a description that the agent matches against your message.

Tutorial to tell the user

After verification, tell the user:

1. Sisyphus strongly recommends Opus 4.7. Using other models may noticeably degrade the experience.
2. Feeling lazy? Just include ultrawork (or ulw) in your prompt. The agent figures out the rest.
3. Need precision? Press Tab to enter Prometheus (Planner) mode, then run /start-work to execute the verified plan.
4. Your own agent/category setup? Read docs/guide/agent-model-matching.md — the assistant can interview the user and tune the config.

Then say Congratulations! 🎉 You have successfully set up oh-my-openagent! Type opencode (or codex) in your terminal to start using it.

Step 7: Light Edition deep dive (Codex CLI)

Skip this section if --platform=opencode. Otherwise, the user installed the Light edition (omo-codex) — here is what landed on disk and what each piece does.

What was installed

• Plugin cache: ~/.codex/plugins/cache/sisyphuslabs/omo/<version>/
• Component binaries: ~/.local/bin/omo-rules, omo-comment-checker, omo-lsp, omo-ultrawork, omo-ulw-loop (or $CODEX_LOCAL_BIN_DIR/omo-* if set)
• Codex config edits: ~/.codex/config.toml gained [features] plugins = true, [features] plugin_hooks = true, [marketplaces.sisyphuslabs] pointing at https://github.com/code-yeongyu/lazycodex.git, [plugins."omo@sisyphuslabs"], and SHA256-pinned [hooks.state."omo@sisyphuslabs:..."] entries

The 5 components

Component	Language	Codex hooks	What it does
rules	TypeScript	SessionStart, UserPromptSubmit, PostToolUse, PostCompact	Injects AGENTS.md, CLAUDE.md, and .omo/rules/** into Codex's context
comment-checker	TypeScript	PostToolUse (apply_patch, edit, write)	Blocks AI-slop comment patterns in generated code
lsp	TypeScript + MCP	MCP server + post-edit hooks	Exposes LSP diagnostics, navigation, symbols, rename via MCP
ultrawork	Python	SessionStart + keyword detector	Detects ulw/ultrawork keyword; syncs bundled agent TOML files into $CODEX_HOME/agents
ulw-loop	TypeScript	Durable orchestration via .omo/ulw-loop/	Multi-goal orchestration with evidence audit trail

Coexistence with OpenCode

The Codex CLI Light edition is fully independent of the OpenCode plugin. You can install both side-by-side. They share no runtime state, no config files, and no model selection. Each emits its own daily telemetry event.

Codex troubleshooting

Symptom	Fix
codex --help does not list the omo plugin	Re-run bunx omo install --platform=codex (idempotent — hook hashes are recomputed)
command not found: omo-rules	Add ~/.local/bin to PATH, or set $CODEX_LOCAL_BIN_DIR to a directory already on PATH
npm install fails mid-install	rm -rf ~/.codex/plugins/cache/sisyphuslabs and retry
Plugin block is present but hooks do not fire	Verify ~/.codex/config.toml contains [features]\nplugins = true\nplugin_hooks = true and [plugins."omo@sisyphuslabs"]
Hook trust hash mismatch warnings	Re-run the installer; hashes are regenerated each install

Step 8: Team Mode (optional, opt-in)

Off by default. Enables a lead-and-members multi-agent system with 12 dedicated tools.

To enable, edit your plugin config:

// ~/.config/opencode/oh-my-openagent.jsonc OR .opencode/oh-my-openagent.jsonc
{
  "team_mode": {
    "enabled": true,
    "max_parallel_members": 4,         // 1..8
    "max_members": 8,                  // 1..8 hard cap
    "tmux_visualization": false,
    "max_messages_per_run": 10000,
    "max_wall_clock_minutes": 120,
    "max_member_turns": 500,
    "base_dir": null,                  // overrides default ~/.omo/teams or <project>/.omo/teams
    "message_payload_max_bytes": 32768,
    "recipient_unread_max_bytes": 262144,
    "mailbox_poll_interval_ms": 3000
  }
}

Restart OpenCode after the change. Twelve new tools unlock: team_create, team_delete, team_shutdown_request, team_approve_shutdown, team_reject_shutdown, team_send_message, team_task_create, team_task_list, team_task_update, team_task_get, team_status, team_list.

Team storage lives under ~/.omo/teams/{name}/ (user scope) or <project>/.omo/teams/{name}/ (project scope — project beats user on collisions).

Member eligibility:

• Eligible: sisyphus, atlas, sisyphus-junior
• Conditional: hephaestus (needs teammate: "allow" permission)
• Hard-rejected at parse: oracle, librarian, explore, multimodal-looker, metis, momus, prometheus (use task/delegate-task instead)

Two skills already ride on top of Team Mode:

• hyperplan — 5 hostile agents tear a plan apart from orthogonal angles before any code is written.
• security-research — 3 vulnerability hunters + 2 PoC engineers audit your codebase in parallel.

Full guide: docs/guide/team-mode.md.

Step 9: Advanced configuration

Config file precedence

Walked configs (closer wins): <pwd up to $HOME>/.opencode/oh-my-openagent.json[c]
                              (legacy basename: oh-my-opencode.json[c])
                            ↓ merged onto
User config:               ~/.config/opencode/oh-my-openagent.json[c]
                              (Windows: %APPDATA%\opencode\)
                            ↓ falls back to
Defaults

Merge rules:

• agents, categories, claude_code: deep merged recursively (prototype-pollution safe)
• disabled_* arrays: Set union (concatenated + deduplicated)
• mcp_env_allowlist: user-only for security; walked configs cannot extend it
• Everything else: override replaces base value

Schema autocomplete in your editor:

"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/oh-my-opencode.schema.json"

Turning features off

Every agent, hook, skill, MCP, command, and tool is configurable via disabled_* arrays:

{
  "disabled_agents": ["multimodal-looker"],
  "disabled_hooks": ["ralph-loop", "ultrawork"],
  "disabled_skills": ["playwright-cli"],
  "disabled_mcps": ["grep_app"],
  "disabled_commands": ["/handoff"],
  "disabled_tools": ["interactive_bash"]
}

Environment variables

Variable	Effect
OMO_INVOCATION_NAME	Overrides detected bin name (oh-my-opencode, omo, lazycodex, etc.). Used to route lazycodex install to --platform=codex.
OMO_DISABLE_POSTHOG=1	Disables all PostHog telemetry for the main plugin
OMO_SEND_ANONYMOUS_TELEMETRY=0	Same effect as above
OMO_CODEX_DISABLE_POSTHOG=1	Disables PostHog telemetry for the Codex CLI Light edition only
OMO_CODEX_SEND_ANONYMOUS_TELEMETRY=0	Same effect as above
OMO_DISABLE_PROCESS_CLEANUP=1	Disables background-agent best-effort process cleanup on parent exit
OMO_OPENCLAW_COMMAND_TIMEOUT_MS	Timeout for OpenClaw outbound shell/HTTP commands
OMO_OPENCLAW_DEBUG=1	Enables OpenClaw debug logging
OMO_OPENCLAW_REPLY_LISTENER_STARTUP_TOKEN	Startup token for OpenClaw reply listener daemon
OMO_OPENCLAW_REPLY_LISTENER_STARTUP_TIMEOUT_MS	Timeout for reply listener startup
OH_MY_OPENCODE_FORCE_BASELINE=1	Forces baseline (non-AVX2) binary selection on x64
OPENCODE_DEFAULT_AGENT	Default agent for omo run (overridden by --agent)
CODEX_LOCAL_BIN_DIR	Overrides ~/.local/bin for Codex component symlinks

Hash-anchored edits (Hashline)

Every Read tool output is tagged with LINE#ID content hashes. The hashline_edit tool rejects edits when the file has changed since the last read. No whitespace reproduction issues, no stale-line errors. Disable with hashline_edit.enabled: false if you need the legacy edit behavior.

OpenClaw (optional outbound notifications)

OpenClaw is a bidirectional external integration: outbound dispatchers fire on session events (idle, error, completion) to Discord/Telegram/HTTP/shell sinks; an optional inbound reply listener daemon polls Discord/Telegram and send-keys replies back into the tracked tmux pane. Configure under the openclaw config block. See src/openclaw/ for the full reference.

Step 10: Maintenance

Command	Purpose
bunx oh-my-openagent doctor	6-category health check (System / Config / TUI Plugin / Tools / Models / Team Mode)
bunx oh-my-openagent boulder	Inspect boulder work-state and per-task stats from .omo/boulder-state/
bunx oh-my-openagent refresh-model-capabilities	Refresh models.json cache from models.dev
bunx oh-my-openagent mcp-oauth login <server-url>	Tier-3 MCP OAuth login (PKCE + DCR)
bunx oh-my-openagent mcp-oauth status	Show OAuth token status
bunx oh-my-openagent get-local-version	Show installed version vs npm latest
bunx oh-my-openagent version	Print the CLI version
bunx oh-my-openagent run <message>	Non-interactive session; waits until todos clear and background tasks idle

Postinstall validates both platform binary resolution and OpenCode version compatibility — the validation runs after every npm install.

Telemetry & Privacy

Anonymous telemetry is enabled by default to track active installations (DAU/WAU/MAU). For both products:

• A single event is sent at most once per UTC day per machine
• Uses a SHA256-hashed installation identifier — never the raw hostname
• PostHog person profiles are not created
• The raw hostname is never transmitted

Per product:

Product	Event name	Sources
Main plugin	oh_my_openagent_daily_active	Session start
Codex CLI Light edition	omo_codex_daily_active	Installer (install_completed) + Codex SessionStart hook (session_start)

Opt-out:

# Disable the main plugin's telemetry
export OMO_DISABLE_POSTHOG=1
# or
export OMO_SEND_ANONYMOUS_TELEMETRY=0

# Disable only the Codex CLI Light edition telemetry
export OMO_CODEX_DISABLE_POSTHOG=1
# or
export OMO_CODEX_SEND_ANONYMOUS_TELEMETRY=0

The global flags (OMO_DISABLE_POSTHOG, OMO_SEND_ANONYMOUS_TELEMETRY) also suppress the Codex CLI Light edition telemetry.

See Privacy Policy and Terms of Service.

Uninstall

Remove the OpenCode plugin

# 1. Remove the plugin entry from opencode.json
jq '.plugin = [.plugin[] | select(. != "oh-my-openagent" and . != "oh-my-opencode")]' \
    ~/.config/opencode/opencode.json > /tmp/oc.json && \
    mv /tmp/oc.json ~/.config/opencode/opencode.json

# 2. Remove plugin config files (optional)
rm -f ~/.config/opencode/oh-my-openagent.jsonc ~/.config/opencode/oh-my-openagent.json \
      ~/.config/opencode/oh-my-opencode.jsonc ~/.config/opencode/oh-my-opencode.json

# 3. Remove project config (if you have one)
rm -f .opencode/oh-my-openagent.jsonc .opencode/oh-my-openagent.json \
      .opencode/oh-my-opencode.jsonc .opencode/oh-my-opencode.json

# 4. Verify removal
opencode --version
# Plugin should no longer be loaded

Remove the Codex CLI Light edition

# 1. Remove the plugin cache
rm -rf ~/.codex/plugins/cache/sisyphuslabs

# 2. Edit ~/.codex/config.toml and remove these blocks:
#    [marketplaces.sisyphuslabs]
#    [plugins."omo@sisyphuslabs"]
#    [hooks.state."omo@sisyphuslabs"]

# 3. Optional: remove the component symlinks
rm -f ~/.local/bin/omo-rules ~/.local/bin/omo-comment-checker \
      ~/.local/bin/omo-lsp ~/.local/bin/omo-ultrawork ~/.local/bin/omo-ulw-loop

Operational notes

• Claude Code compatibility is supported (hooks, commands, skills, MCPs, plugins).
• Claude Code plugin discovery load timeout is 10 seconds.
• Runtime logger: oh-my-opencode.log in the OS temp dir (/tmp on Linux, /var/folders/.../T/ on macOS, %TEMP% on Windows), 50 MB cap with .1/.2 backup segments.
• Dual-publish during the rename transition: oh-my-opencode and oh-my-openagent are both published. Inside opencode.json, the compatibility layer prefers the entry "oh-my-openagent", while legacy "oh-my-opencode" entries still load with a warning. Plugin config loading recognises both oh-my-openagent.json[c] and oh-my-opencode.json[c] during the transition. If doctor warns about the legacy package name, update your opencode.json plugin entry.