## 1. Project Overview & Quickstart (code-yeongyu/oh-my-openagent) ## File: README.md > [!NOTE] > **OmO for Codex is here: try LazyCodex** > > We loved Anthropic models enough to get blocked. Now we are backing Codex. > If you are an OmO fan but the setup felt like too much, use LazyCodex. OmO for Codex has shipped: > ```bash > npx lazycodex-ai install > ``` > Learn more at [lazycodex.ai](https://lazycodex.ai). > [!NOTE] > **Multi-Harness Agent OS Refactor in Progress** > > We are restructuring the codebase to support multiple agent harnesses (OpenCode, Codex, Pi, and others). If you are interested in contributing, please read the [ROADMAP](./ROADMAP.md) first. PRs related to roadmap work should use the `ROADMAP` label. > [!TIP] > **Building in Public** > > The maintainer builds and maintains oh-my-openagent in real-time with Jobdori, an AI assistant running on a heavily customized fork of OpenClaw. > Every feature, every fix, every issue triage — live in our Discord. > > [](https://discord.gg/PUwSMR9XNk) > > [**→ Watch it happen in #building-in-public**](https://discord.gg/PUwSMR9XNk) > [!NOTE] > > [](https://sisyphuslabs.ai) > > **OmO is maintained by Jobdori, the AI assistant shown above. Meet your own Jobdori — Dori. Join the waitlist [here](https://sisyphuslabs.ai).** > [!TIP] > Be with us! > > | [](https://discord.gg/PUwSMR9XNk) | Join our [Discord community](https://discord.gg/PUwSMR9XNk) to connect with contributors and fellow `oh-my-openagent` users. | > | :-----| :----- | > | [](https://x.com/justsisyphus) | Updates for `oh-my-openagent` used to be posted on my X account. Since it was mistakenly suspended, [@justsisyphus](https://x.com/justsisyphus) now posts updates on my behalf. | > | [](https://github.com/code-yeongyu) | Follow [@code-yeongyu](https://github.com/code-yeongyu) on GitHub for more projects. | > This is oh-my-openagent, running Team Mode. With Kimi K3 and GPT-5.6 Sol. > Anthropic [**blocked OpenCode because of us.**](https://x.com/thdxr/status/2010149530486911014) **Yes, this is true.** > They want you locked in. Claude Code is a nice prison, but it's still a prison. > > You don't need to pay $200 for 2 hours of work. > The future isn't picking one winner; it's orchestrating them all. Models get cheaper every month. Smarter every month. No single provider will dominate. We're building for that open market, not their walled gardens. ## Reviews > "It made me cancel my Cursor subscription. Unbelievable things are happening in the open source community." - [Arthur Guiot](https://x.com/arthur_guiot/status/2008736347092382053?s=20) > "If Claude Code does in 7 days what a human does in 3 months, Sisyphus does it in 1 hour. It just works until the task is done. It is a discipline agent." - B, Quant Researcher > "Knocked out 8000 eslint warnings with Oh My Opencode, just in a day" - [Jacob Ferrari](https://x.com/jacobferrari_/status/2003258761952289061) > "I converted a 45k line tauri app into a SaaS web app overnight using Ohmyopencode and ralph loop. Started with interview me prompt, asked it for ratings and recommendations on the questions. It was amazing to watch it work and to wake up this morning to a mostly working website!" - [James Hargis](https://x.com/hargabyte/status/2007299688261882202) > "use oh-my-opencode, you will never go back" - [d0t3ch](https://x.com/d0t3ch/status/2001685618200580503) > "I haven't really been able to articulate exactly what makes it so great yet, but the development experience has reached a completely different dimension." - [ 苔硯:こけすずり](https://x.com/kokesuzuri/status/2008532913961529372?s=20) > "Experimenting with open code, oh my opencode and supermemory this weekend to build some minecraft/souls-like abomination." > "Asking it to add crouch animations while I go take my post-lunch walk. [Video]" - [MagiMetal](https://x.com/MagiMetal/status/2005374704178373023) > "You guys should pull this into core and recruit him. Seriously. It's really, really, really good." - Henning Kilset > "Hire @yeon_gyu_kim if you can convince him, this dude has revolutionized opencode." - [mysticaltech](https://x.com/mysticaltech/status/2001858758608376079) > "Oh My OpenCode Is Actually Insane" - [YouTube - Darren Builds AI](https://www.youtube.com/watch?v=G_Snfh2M41M) --- # Oh My OpenAgent You're juggling Claude Code, Codex, and random OSS models. Configuring workflows. Debugging agents. We did the work. Tested everything. Kept what actually shipped. Install oh-my-openagent. Type `ultrawork`. Done. ## Installation oh-my-openagent ships in three editions of the same product: two plugins that load into a host you already run, plus one standalone edition. - **Ultimate Edition (omo for OpenCode)** — full omo. 11 agents, 54+ lifecycle hooks, 5 built-in MCPs, all slash commands, Team Mode, ulw-loop, ultrawork, hashline edits — everything. - **Light Edition (omo for Codex CLI)** — the portable components that fit Codex's plugin system: `rules`, `comment-checker`, `git-bash`, `lsp`, `ultrawork`, `ulw-loop`, `start-work-continuation`, and `telemetry`, plus plugin-scoped MCPs for `grep_app`, `context7`, `codegraph`, `git_bash`, and `lsp`, and the shared `ast-grep` skill. No agent orchestration and no `team_*` tools — Codex CLI's own surface does that work. - **Senpi Edition (standalone, beta)** — the native `omo` command with the OMO extension built in. It installs from `omo-ai@beta` rather than loading into OpenCode or Codex. Pick the edition(s) you want. ### TL;DR | You want | Run | What lands on disk | | :--- | :--- | :--- | | **Ultimate** (OpenCode) | `bunx oh-my-openagent install` (TUI walks you through it) | Plugin registered in `opencode.json` + agent/model config + provider auth prompts | | **Light** (Codex CLI) | `npx lazycodex-ai install` | `~/.codex/plugins/cache/sisyphuslabs/omo/` + local Codex marketplace cache + `~/.codex/config.toml` marketplace/plugin/agent blocks + optional autonomous permissions + component CLIs in `~/.local/bin` | | **Both** | `bunx oh-my-openagent install --platform=both` | Both of the above | | **Senpi edition** (beta) | `npm i omo-ai@beta`, then `omo` | The `omo` command: pinned senpi release with the OMO extension built in. Beta channel only; a bare `npm i omo-ai` fails by design. See the [install guide](docs/guide/installation.md#senpi-edition-beta-omo-via-npm-omo-ai). | `lazycodex-ai` defaults to the Codex Light installer and runs through Node/npm. `--platform` on the shared `omo-agent-toolkit` CLI still defaults to `opencode` (Ultimate). ### Which edition should I pick? - Already use OpenCode, or want the most-tested path? Choose **Ultimate**: `bunx oh-my-openagent install`. - Already use Codex CLI? Choose **Light**: `npx lazycodex-ai install`. - Want one command without installing a host first? Choose **Senpi/native (beta)**: `npm i omo-ai@beta`. Ultimate and Light are plugins that load into a host you already run. Senpi is standalone: it ships a pinned Senpi engine with OMO built in. For Senpi, the `@beta` tag is required; bare `npm i omo-ai` fails by design. Do not install plain `omo` from npm: it is an unrelated package by a different author. ### For Humans **Strongly recommended: let an LLM agent install this for you.** The Ultimate edition setup involves subscription detection, model selection across 11 agents, and per-provider authentication — humans fat-finger these. An LLM agent reads the full guide and walks every step correctly. Paste this prompt into Claude Code, AmpCode, Cursor, or any agent: ``` 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 ``` If you only want the **Light edition** (Codex CLI), the installer asks whether to configure Codex for autonomous full-permissions mode. You can run it yourself in one line: ```bash npx lazycodex-ai install # non-interactive recommended mode: npx lazycodex-ai install --no-tui --codex-autonomous ``` For the Light edition, Bun is not required. Use `npx lazycodex-ai install` from a Node/npm environment. Global installation is not officially supported; the installer writes the Codex plugin into `~/.codex/`. ### For LLM Agents Fetch the full guide and follow it step by step: ```bash curl -fsSL https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md ``` The guide covers: platform selection, the subscription interview, provider authentication (Anthropic / Gemini / Copilot / Z.ai / OpenCode Zen), the agent-to-model matching matrix, modes (`ultrawork`, `search`, `analyze`, `team`, `hyperplan`), slash commands, the Light edition's 8 Codex components, Team Mode, and uninstall. Don't summarize it; read it end to end. ### Note on package and command names The published npm package and CLI binary are still named `oh-my-opencode` (dual-published as `oh-my-openagent` during the rename transition). Inside `opencode.json`, the compatibility layer prefers the plugin entry `oh-my-openagent`, while legacy `oh-my-opencode` entries still load with a warning. Plugin config files still commonly use `oh-my-opencode.json[c]`; both legacy and renamed basenames are recognized. The recommended `bunx`/`npx` invocation is `oh-my-openagent install` (or the original `oh-my-opencode install`). Once installed, the short command is `omo-agent-toolkit`. The `omo` bin was removed from these packages in this major release; the name now belongs to the senpi-native edition, installed with `npm i omo-ai@beta` (beta channel only). Do **not** use `bunx omo` or `npx omo`: `omo` on npm is a different, unrelated package by a different author, and those commands resolve to it. The senpi edition's package name is `omo-ai`. `lazycodex-ai` is a single-purpose Node/npm installer package: `npx lazycodex-ai install` routes directly to the Codex Light installer. It is not the Codex marketplace name (the marketplace repository is `code-yeongyu/lazycodex`). Codex sees marketplace `sisyphuslabs` and plugin `omo`, enabled as `omo@sisyphuslabs`. ### Telemetry 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** using a SHA256-hashed installation identifier (never the raw hostname), and PostHog person profiles are not created. The main plugin emits `omo_daily_active` from plugin load (`plugin_loaded`) and CLI run (`run_started`) sources; the Codex CLI Light edition emits `omo_codex_daily_active` from two sources (`install_completed` and `session_start`). Opt out per product: - Main plugin: set `"telemetry": false` in oh-my-openagent config, `OMO_DISABLE_POSTHOG=1`, or `OMO_SEND_ANONYMOUS_TELEMETRY=0` - Codex CLI Light edition: `OMO_CODEX_DISABLE_POSTHOG=1` or `OMO_CODEX_SEND_ANONYMOUS_TELEMETRY=0` (the global flags also disable Codex) See [Privacy Policy](docs/legal/privacy-policy.md) and [Terms of Service](docs/legal/terms-of-service.md). --- ## Skip This README We're past the era of reading docs. Just paste this into your agent: ``` Read this and tell me why it's not just another boilerplate: https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/README.md ``` ## ROADMAP We are restructuring the codebase to support multiple agent harnesses (OpenCode, Codex, Pi, Claude Code, and others). The most urgent work is the package layering refactor: separating pure TypeScript core logic, MCP servers, skills, and adapter shims into distinct layers so the same logic can be reused across harnesses without duplication. If you want to contribute, read the [ROADMAP](./ROADMAP.md) first. PRs related to this refactor should use the `ROADMAP` label so we can track them. ## Highlights ### 🪄 `ultrawork` You're actually reading this? Wild. Install. Type `ultrawork` (or `ulw`). Done. Everything below, every feature, every optimization: you don't need to know any of it. It just works. Even with only the following subscriptions, `ultrawork` works well (this project is not affiliated; these are personal recommendations): - [ChatGPT Subscription ($20)](https://chatgpt.com/) - [Kimi Code Subscription ($19)](https://www.kimi.com/code) - [GLM Coding Plan ($10)](https://z.ai/subscribe) - If you're eligible for pay-per-token, using Kimi and Gemini models won't cost much. | | Feature | Edition | What it does | | :---: | :------------------------------------------------------- | :------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 🤖 | **Discipline Agents** | Ultimate | Sisyphus orchestrates Hephaestus, Oracle, Librarian, Explore. A full AI dev team in parallel. | | 🧩 | **Codex CLI Light Edition** | Light | Portable OMO components (rules, comment-checker, git-bash, LSP, ultrawork, ulw-loop, start-work continuation, telemetry) running inside OpenAI Codex CLI. Install via `npx lazycodex-ai install`. | | 👥 | **Team Mode** (v4.0, opt-in) | Ultimate | Lead agent + up to 8 parallel members, real-time tmux visualization, dedicated `team_*` tools. Powers `hyperplan` (5 hostile critics) and `security-research` (3 hunters + 2 PoC engineers). [Docs →](docs/guide/team-mode.md) | | ⚡ | **`ultrawork` / `ulw`** | Both | One word. Every agent activates. Doesn't stop until done. | | 🚪 | **[IntentGate](https://factory.ai/news/terminal-bench)** | Ultimate | Analyzes true user intent before classifying or acting. No more literal misinterpretations. (Light edition only recognises the `ultrawork`/`ulw` keyword.) | | 🔗 | **Hash-Anchored Edit Tool** | Ultimate | `LINE#ID` content hash validates every change. Zero stale-line errors. Inspired by [oh-my-pi](https://github.com/can1357/oh-my-pi). [The Harness Problem →](https://blog.can.ac/2026/02/12/the-harness-problem/) | | 🛠️ | **LSP integration** | Both | Diagnostics, navigation, symbols, workspace rename. IDE precision for agents. Same LSP MCP server in both editions. | | 🔎 | **AST-Grep** | Ultimate | Pattern-aware code search and rewriting across 25 languages. | | 🧠 | **Background Agents** | Ultimate | Fire 5+ specialists in parallel. Context stays lean. Results when ready. | | 📚 | **Built-in MCPs** (web/docs/code search) | Ultimate | Exa (web search), Context7 (official docs), Grep.app (GitHub search). Always on. | | 🔁 | **Goal / `/goal`** | Ultimate | Persistent per-session objective. Re-injects a continuation prompt on every idle until a completion audit says it's done. | | ✅ | **Todo Enforcer** | Ultimate | Agent goes idle? System yanks it back. Your task gets done, period. | | 💬 | **Comment Checker** | Both | No AI slop in comments. Code reads like a senior wrote it. | | 📐 | **Rules Injection** (`AGENTS.md` / `.omo/rules/**`) | Both | Project rules and AGENTS.md auto-loaded into the agent's context at every prompt. | | 🎯 | **Ulw Loop** | Both | Durable multi-goal orchestration with evidence audit, backed by `.omo/ulw-loop/`. | | 🖥️ | **Tmux Integration** | Ultimate | Full interactive terminal. REPLs, debuggers, TUIs. All live. | | 🔌 | **Claude Code Compatible** | Ultimate | Your hooks, commands, skills, MCPs, and plugins? All work here. | | 🧬 | **Skill-Embedded MCPs** | Ultimate | Skills carry their own MCP servers. No context bloat. | | 📋 | **Prometheus Planner** | Ultimate | Interview-mode strategic planning before any execution. | | 🔍 | **`/init-deep`** | Ultimate | Auto-generates hierarchical `AGENTS.md` files throughout your project. Great for both token efficiency and your agent's performance. | > **Edition legend.** **Ultimate** = OpenCode-only (`bunx oh-my-openagent install`). **Light** = Codex CLI-only (`npx lazycodex-ai install`). **Both** = shipped in both editions, often with slightly different implementations under the hood. ### Discipline Agents | | | | --- | --- | **Sisyphus** (`claude-opus-5` / **`kimi-k3`** / **`glm-5`** ) is your main orchestrator. He plans, delegates to specialists, and drives tasks to completion with aggressive parallel execution. He does not stop halfway. Claude Opus 5 and Kimi K3 are the recommended defaults. **Hephaestus** (`gpt-5.6-sol` through OpenAI, GitHub Copilot, Vercel, or OpenCode at medium effort) is your autonomous deep worker. Give him a goal, not a recipe. He explores the codebase, researches patterns, and executes end-to-end without hand-holding. *The Legitimate Craftsman.* **Prometheus** (`claude-fable-5` / **`kimi-k3`**) is your strategic planner. Interview mode: he asks questions, identifies scope, and builds a detailed plan before a single line of code is touched. Every agent is tuned to its model's specific strengths. No manual model juggling. [Learn more →](docs/guide/overview.md) > Anthropic [blocked OpenCode because of us.](https://x.com/thdxr/status/2010149530486911014) That's why Hephaestus is called "The Legitimate Craftsman." The irony is intentional. > > We run best on Opus or Kimi K3, but Kimi K3 + GPT-5.6 Sol already beats vanilla Claude Code. Zero config needed. ### Team Mode (v4.0) One agent is fast. A coordinated team is *devastating*. **Team Mode** turns oh-my-openagent from "one agent with subagents" into a real multi-agent system. A lead agent orchestrates a team of category-specialized members, all running **in parallel** and communicating through dedicated tools (`team_create`, `team_send_message`, `team_task_create`, `team_status`, ...). Watch every member work simultaneously in a tmux layout with focus + grid windows. ```jsonc // .opencode/oh-my-openagent.jsonc { "team_mode": { "enabled": true, "max_parallel_members": 4, "tmux_visualization": true } } ``` Restart opencode and the `team_*` tool family unlocks. Two skills already ride on top: - **`hyperplan`** — 5 hostile agents tear apart your plan from orthogonal angles before a single line of code is written. - **`security-research`** — 3 vulnerability hunters + 2 PoC engineers audit your codebase in parallel, with severity calibrated by *actual exploitability*. > **Off by default. Enable it when you want it.** [Full Team Mode guide →](docs/guide/team-mode.md) ### Agent Orchestration When Sisyphus delegates to a subagent, it doesn't pick a model. It picks a **category**. The category maps automatically to the right model: | Category | What it's for | | :------------------- | :--------------------------------- | | `visual-engineering` | Frontend, UI/UX, design | | `deep` | Autonomous research + execution | | `quick` | Single-file changes, typos | | `ultrabrain` | Hard logic, architecture decisions | The agent says what kind of work it needs; the harness picks the right model. `ultrabrain` now routes to GPT-5.6 Sol xhigh through OpenAI or Vercel when available, then GPT-5.6 Sol xhigh. You touch nothing. ### Claude Code Compatibility You dialed in your Claude Code setup. Good. Every hook, command, skill, MCP, plugin works here unchanged. Full compatibility, including plugins. ### World-Class Tools for Your Agents LSP, AST-Grep, Tmux, and MCP, actually integrated, not duct-taped together. - **LSP**: `lsp_rename`, `lsp_goto_definition`, `lsp_find_references`, `lsp_diagnostics`. IDE precision for every agent. - **AST-Grep**: Pattern-aware code search and rewriting across 25 languages. - **Tmux**: Full interactive terminal. REPLs, debuggers, TUI apps. Your agent stays in session. - **MCP**: Web search, official docs, GitHub code search. All baked in. ### Skill-Embedded MCPs MCP servers eat your context budget. We fixed that. Skills bring their own MCP servers. They spin up on demand, scoped to the task, and go away when done. The context window stays clean. ### Codes Better. Hash-Anchored Edits The harness problem is real. Most agent failures aren't the model's fault; it's the edit tool. > *"None of these tools give the model a stable, verifiable identifier for the lines it wants to change... They all rely on the model reproducing content it already saw. When it can't - and it often can't - the user blames the model."* > > - [Can Bölük, The Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) Inspired by [oh-my-pi](https://github.com/can1357/oh-my-pi), we built **Hashline**. Every line the agent reads comes back tagged with a content hash: ``` 11#VK| function hello() { 22#XJ| return "world"; 33#MB| } ``` The agent edits by referencing those tags. If the file has changed since the last read, the hash won't match and the edit is rejected before any corruption. No whitespace reproduction. No stale-line errors. Grok Code Fast 1: **6.7% → 68.3%** success rate, just from changing the edit tool. ### Deep Initialization. `/init-deep` Run `/init-deep`. It generates hierarchical `AGENTS.md` files: ``` project/ ├── AGENTS.md ← project-wide context ├── src/ │ ├── AGENTS.md ← src-specific context │ └── components/ │ └── AGENTS.md ← component-specific context ``` Agents auto-read relevant context. Zero manual management. ### Planning. Prometheus Complex task? Don't prompt and pray. `/start-work` calls Prometheus. He **interviews you like a real engineer**, identifies scope and ambiguities, and builds a verified plan before touching code. The agent knows what it's building before it starts. ### Skills Skills aren't just prompts. Each brings: - Domain-tuned system instructions. - Embedded MCP servers, on demand. - Scoped permissions so agents stay in bounds. Built-ins: `playwright` (browser automation), `git-master` (atomic commits, rebase surgery), `frontend` (design-first UI). Add your own under `.opencode/skills/*/SKILL.md` or `~/.config/opencode/skills/*/SKILL.md`. **Want the full feature breakdown?** See the **[Features Documentation](docs/reference/features.md)** for agents, hooks, tools, MCPs, and everything else in detail. --- > **New to oh-my-openagent?** Read the **[Overview](docs/guide/overview.md)** to understand what you have, or check the **[Orchestration Guide](docs/guide/orchestration.md)** for how agents collaborate. ## Uninstallation To remove oh-my-openagent: 1. **Remove the plugin from your OpenCode config** Edit `~/.config/opencode/opencode.json` (or `opencode.jsonc`) and remove either `"oh-my-openagent"` or the legacy `"oh-my-opencode"` entry from the `plugin` array: ```bash # Using jq 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 configuration files (optional)** ```bash # Remove plugin config files recognized during the compatibility window 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 # Remove project config (if exists) rm -f .opencode/oh-my-openagent.jsonc .opencode/oh-my-openagent.json \ .opencode/oh-my-opencode.jsonc .opencode/oh-my-opencode.json ``` 3. **Verify removal** ```bash opencode --version # Plugin should no longer be loaded ``` 4. **Remove omo-codex (Codex CLI Light edition)** ```bash npx lazycodex-ai uninstall # backward-compatible alias: npx lazycodex-ai cleanup omo-agent-toolkit uninstall --platform=codex # backward-compatible alias: omo-agent-toolkit cleanup --platform=codex ``` The uninstall command removes managed `sisyphuslabs` Codex cache/marketplace state, strips `omo@sisyphuslabs` plugin and hook-state blocks from `~/.codex/config.toml` after writing a backup, and removes agent TOML links listed in the install manifest. If a specific project still has old project-local Codex plugin state, run the command from that project or pass `--project `; it repairs known project-local `.codex/config.toml` conflicts and reports project-local `.codex` artifacts without deleting project-owned files. ## Features Features you'll think should've always existed. Once you use them, you can't go back. See full [Features Documentation](docs/reference/features.md). **Quick Overview:** - **Agents**: Sisyphus (the main agent), Prometheus (planner), Oracle (architecture/debugging), Librarian (docs/code search), Explore (fast codebase grep), Multimodal Looker - **Background Agents**: Run multiple agents in parallel like a real dev team - **LSP & AST Tools**: Refactoring, rename, diagnostics, AST-aware code search - **Hash-anchored Edit Tool**: `LINE#ID` references validate content before applying every change. Surgical edits, zero stale-line errors - **Context Injection**: Auto-inject AGENTS.md, README.md, conditional rules - **Claude Code Compatibility**: Full hook system, commands, skills, agents, MCPs - **Built-in MCPs**: websearch (Exa), context7 (docs), grep_app (GitHub search) — injected at runtime by the plugin; not visible in `opencode mcp list` (see [MCP docs](docs/reference/features.md#native-vs-plugin-injected-mcps)) - **Session Tools**: List, read, search, and analyze session history - **Productivity Features**: Goal, Todo Enforcer, Comment Checker, Think Mode, and more - **Doctor Command**: Built-in diagnostics (`bunx oh-my-opencode doctor`) verify plugin registration, config, models, and environment - **Model Fallbacks**: `fallback_models` can mix plain model strings with per-fallback object settings in the same array - **File Prompts**: Load prompts from files with `file://` support in agent configurations - **Session Recovery**: Automatic recovery from session errors, context window limits, and API failures - **Model Setup**: Agent-model matching is built into the [Installation Guide](docs/guide/installation.md#step-5-understand-your-model-setup) ## Configuration Opinionated defaults, adjustable if you insist. See [Configuration Documentation](docs/reference/configuration.md). **Quick Overview:** - **Config Locations**: User config plus walked `.opencode/oh-my-openagent.json[c]` configs up to `$HOME`; closest wins. Legacy `oh-my-opencode.json[c]` still works. - **JSONC Support**: Comments and trailing commas supported - **Agents**: Override models, temperatures, prompts, and permissions for any agent - **Built-in Skills**: `playwright` (browser automation), `git-master` (atomic commits) - **Sisyphus Agent**: Main orchestrator with Prometheus (Planner) and Metis (Plan Consultant) - **Background Tasks**: Configure concurrency limits per provider/model - **Categories**: Domain-specific task delegation (`visual`, `business-logic`, custom) - **Hooks**: 54+ lifecycle hooks (61 with Team Mode), all configurable via `disabled_hooks` - **MCPs**: Built-in websearch (Exa), context7 (docs), grep_app (GitHub search) — runtime-injected, not shown in `opencode mcp list` - **LSP**: Full LSP support with refactoring tools - **Experimental**: Aggressive truncation, auto-resume, and more ## Author's Note **Want the philosophy?** Read the [Ultrawork Manifesto](docs/manifesto.md). --- I burned through $24K in LLM tokens on personal projects. Tried every tool. Configured everything to death. OpenCode won. Every problem I hit, the fix is baked into this plugin. Install and go. If OpenCode is Debian/Arch, oh-my-openagent is Ubuntu/[Omarchy](https://omarchy.org/). Heavily influenced by [AmpCode](https://ampcode.com) and [Claude Code](https://code.claude.com/docs/overview). Features ported, often improved. Still building. It's **Open**Code. Other harnesses promise multi-model orchestration. We ship it. Stability too. And features that actually work. I'm this project's most obsessive user: - Which model has the sharpest logic? - Who's the debugging god? - Who writes the best prose? - Who dominates frontend? - Who owns backend? - What's fastest for daily driving? - What are competitors shipping? This plugin is the distillation. Take the best. Got improvements? PRs welcome. **Stop agonizing over harness choices.** **I'll research, steal the best, and ship it here.** Sounds arrogant? Have a better way? Contribute. You're welcome. No affiliation with any project or model mentioned. Just personal experimentation. Credit: The LazyCodex name idea is inspired by [LazyVim](https://github.com/LazyVim/LazyVim). The Ultragoal and UltraQA ideas are inspired by [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex), reimplemented from concept for OmO. 99% of this project was built with OpenCode. I don't really know TypeScript, **but I personally reviewed and largely rewrote this doc.** ## Loved by professionals at - [Indent](https://indentcorp.com) - Makers of Spray (influencer marketing solution), vovushop (cross-border commerce platform), and vreview (AI commerce review marketing solution). - [Google](https://google.com) - [Microsoft](https://microsoft.com) - [Vercel](https://vercel.com) - [ELESTYLE](https://elestyle.jp) - Makers of elepay (multi-mobile payment gateway) and OneQR (mobile application SaaS for cashless solutions). - [Deepgram](https://deepgram.com) *Special thanks to [@junhoyeo](https://github.com/junhoyeo) for this amazing hero image.* --- ## File: docs/guide/installation.md # Installation oh-my-openagent ships in **three editions** of the same product: two plugins that load into a host you already run, plus one standalone edition. - **Ultimate Edition (omo for [OpenCode](https://opencode.ai))** — 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](https://github.com/openai/codex))** - the portable components that fit Codex's plugin system: `codegraph`, `comment-checker`, `git-bash`, `lazycodex-executor-verify`, `rules`, `lsp`, `telemetry`, `teammode`, `start-work-continuation`, `ulw-loop`, and `ultrawork`, plus plugin-scoped MCPs for `grep_app`, `context7`, `codegraph`, `git_bash`, and `lsp`, and the shared `ast-grep` skill. It has no OpenCode agent registry or `team_*` tool family, but ships Codex-native agent roles and the script-and-skill-driven `teammode` component. - **Senpi Edition (standalone, beta)** — the native `omo` command with the OMO extension built in. It installs from `omo-ai@beta` instead of loading as a plugin into OpenCode or Codex. 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 oh-my-openagent install` (TUI walks you through it) | Plugin registered in `opencode.json`, agent/model config, provider auth | | Light (Codex CLI) | `npx lazycodex-ai install` | `~/.codex/plugins/cache/sisyphuslabs/omo/`, stable Codex marketplace snapshot, `~/.codex/config.toml` marketplace/plugin/agent blocks, optional autonomous Codex permissions, component CLIs in `~/.local/bin` | | Both | `bunx oh-my-openagent install --platform=both` | Both of the above | Both `lazycodex-ai` and `lazycodex` are shipped bin aliases that default to the Codex Light installer and run through Node/npm. `--platform` on the shared `omo-agent-toolkit` CLI still defaults to `opencode` (Ultimate). `lazycodex` is also the repository identity that hosts the marketplace bundle. Neither alias is the Codex marketplace name. ## Which edition should I pick? - Already use OpenCode, or want the most-tested path? Choose **Ultimate**: `bunx oh-my-openagent install`. - Already use Codex CLI? Choose **Light**: `npx lazycodex-ai install`. - Want one command without installing a host first? Choose **Senpi/native (beta)**: `npm i omo-ai@beta`. Ultimate and Light are plugins that load into a host you already run. Senpi is standalone: it ships a pinned Senpi engine with OMO built in. For Senpi, the `@beta` tag is required; bare `npm i omo-ai` fails by design. Do not install plain `omo` from npm: it is an unrelated package by a different author. ## 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 whether to configure Codex for autonomous full-permissions mode. This is recommended for agent-style use: `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, `network_access = "enabled"`, and notice warnings hidden. Use `--codex-autonomous` or `--no-codex-autonomous` to choose non-interactively: ```bash npx lazycodex-ai install # non-interactive recommended mode: npx lazycodex-ai install --no-tui --codex-autonomous ``` It writes managed Codex Light state to `~/.codex/` and does not touch OpenCode or provider flags. During migration from older Codex plugin installs it may also repair the current project's `.codex/config.toml` if that project has the known `multi_agent_v2` plus legacy `[agents] max_threads` conflict; project-owned `.codex` artifacts are reported, not deleted. Global Codex config will register marketplace `sisyphuslabs` from the local built cache under `~/.codex/plugins/cache/sisyphuslabs`, enable plugin `omo@sisyphuslabs`, and write a valid `[features.multi_agent_v2]` limit table. The installer never enables MultiAgentV2; if it finds an explicit legacy `multi_agent_v2 = false` shorthand, it preserves that disable as table-form `enabled = false`. On Windows, keep the direct `npx lazycodex-ai install ...` form above. Do not rewrite it into an `npx --package` command that launches the `omo-agent-toolkit install` bin indirectly; that package-manager shape can fail before the installer starts. On native Windows Codex installs, the installer discovers Git Bash before writing Codex config. It checks `OMO_CODEX_GIT_BASH_PATH`, standard Git for Windows locations, and then PATH. If Git Bash is missing, it prints the install guidance shown here and stops without running `winget` or changing system dependencies: ```powershell winget install --id Git.Git -e --source winget where bash ``` If Git is installed somewhere custom, set the path before rerunning the installer: ```cmd setx OMO_CODEX_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe" ``` ```powershell $env:OMO_CODEX_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe" ``` Codex may still start Windows shell calls through its own defaults. The Light edition does not write a global Codex shell config; instead it verifies Git Bash is available, enables the Windows-only `git_bash` MCP policy, and injects guidance before the first shell-like call. After compaction, the reminder resets so the next shell-like call gets the same `git_bash` recommendation. > **Clean install note for older Codex plugin users.** Before installing the Light edition into a Codex home that previously used another Codex plugin bundle, uninstall the older bundle first, then re-run this installer. Multiple bundles may write Codex marketplace plugins, lifecycle hooks, and the `ultrawork`/`ulw` keyword into the same `~/.codex`, so a clean Codex home avoids stale shared `config.toml` keys and duplicate hooks. > > To remove the Light edition after migration, run `npx lazycodex-ai uninstall`. It removes managed `sisyphuslabs` Codex cache/marketplace state, strips `omo@sisyphuslabs` plugin and hook-state blocks from `~/.codex/config.toml` with a backup, and removes managed agent TOML files from `~/.codex/agents/`. `cleanup` remains available as a backward-compatible alias. > If Codex still fails only inside one project with `agents.max_threads cannot be set when multi_agent_v2 is enabled`, run `npx lazycodex-ai install` from that project. The installer repairs project-local `.codex/config.toml` layers from the project root to the current directory, removes conflicting legacy `[agents] max_threads` only when MultiAgentV2 is enabled, and writes timestamped backups next to changed files. ### Install from the Codex marketplace (in-app) > **Experimental, additive path.** `npx lazycodex-ai install` above remains the primary, fully supported route. The marketplace bundle is hosted in this project's own [lazycodex](https://github.com/code-yeongyu/lazycodex) repository — it is not an OpenAI curated listing. The same Light edition can be installed entirely from inside Codex through its plugin marketplace, with no npx step. **TUI route.** In a Codex session, type `/plugins`, open the **Add Marketplace** tab ("Add a marketplace from a Git repo or local root."), and enter the marketplace source: ``` https://github.com/code-yeongyu/lazycodex ``` Then pick `omo` from the `sisyphuslabs` marketplace in the same `/plugins` menu and install it. **CLI route** — the equivalent two-liner: ```bash codex plugin marketplace add https://github.com/code-yeongyu/lazycodex codex plugin add omo@sisyphuslabs ``` **First session: approve the hooks.** On the next `codex` launch the startup hooks review lists every omo hook as new. Review and approve them — no omo hook runs before you approve, and the bootstrap below cannot start until the hooks are trusted. **Bootstrap notice + restart.** The first approved session prints this status line: ``` LazyCodex bootstrap running in background — restart the session when it completes ``` A detached worker finishes the install in the background (the `sg` download is the slowest part). Restart the Codex session once it completes — the next session starts fully wired and the notice no longer appears. **What bootstrap does:** - writes the managed `~/.codex/config.toml` blocks: marketplace source preserved, `omo@sisyphuslabs` plugin enabled, managed `[agents.*]` entries, and re-stamped SHA256 `[hooks.state."omo@sisyphuslabs:..."]` trust hashes - copies bundled Codex agent TOMLs into `~/.codex/agents/` - links the top-level `omo-agent-toolkit` runtime wrapper plus component CLIs (`omo-rules`, `omo-lsp`, …) into `~/.local/bin` (or `$CODEX_LOCAL_BIN_DIR`; isolated `CODEX_HOME` installs use `/bin`) - provisions a checksum-pinned standalone `sg` (ast-grep) binary into `/runtime/ast-grep/-/` for the `ast-grep` skill - on native Windows, provisions a pinned Node LTS runtime into `/runtime/node/` when `node` is missing (see the Windows status below) - records every run in the plugin data dir: `/plugins/data/omo-sisyphuslabs/bootstrap/state.json` plus a JSONL `bootstrap.log` (Windows adds a `ps-bootstrap.log` transcript) **What bootstrap does NOT do:** - It **never writes Codex permission settings.** `approval_policy`, `sandbox_mode`, and `network_access` are left untouched. Autonomous mode stays an explicit npx installer choice — `npx lazycodex-ai install --no-tui --codex-autonomous` (see [the one-liner section](#light-codex-cli--one-line-no-agent-needed)). - It does not run the npx self-update for healthy marketplace-managed installs. The auto-update hook logs the skip and surfaces this guidance instead: "Auto-update skipped: this LazyCodex install is managed by the Codex plugin marketplace, so the npx self-update was not started. Tell the user to upgrade with `codex plugin marketplace upgrade sisyphuslabs`, and that Codex will ask them to re-approve hooks after the upgrade." If the hook detects stale local marketplace cache/bin state (for example, a local manifest or managed `ulw` link points at a deleted payload), it may start the npx installer as a local repair and ask you to restart the Codex session afterward. - It never persists anything under the Codex-managed plugin cache directory itself; all bootstrap state lives in the plugin data dir above. **Upgrading — and recovering hook approval:** 1. Run `codex plugin marketplace upgrade sisyphuslabs`. 2. Relaunch `codex`. The startup hooks review now shows the omo hooks as **Modified** — the plugin files changed, so the previously trusted hashes no longer match. This is expected after every upgrade, not a sign of tampering. 3. Re-approve the hooks in that review. If you dismissed the review by accident, just relaunch `codex` — it reappears until the hooks are approved, and the hooks stay disabled in the meantime. 4. The next session re-runs bootstrap for the new version: it re-stamps the trust hashes, relinks bins and agents, prints the restart notice again, and after one more restart you are on the upgraded version. **Degraded modes.** Bootstrap is degraded-not-fatal: a failed step is recorded in `state.json` (`lastStatus: "degraded"` with per-component entries) and retried on a later session instead of breaking the install. The ones you may actually notice: | Mode | What you see | What to do | |---|---|---| | `omo-agent-toolkit` absent | The top-level `omo-agent-toolkit` command was not linked because the installed payload is old or incomplete and lacks the root CLI runtime. Current marketplace payloads ship `dist/cli/index.js` plus `dist/cli-node/index.js`, so this should not appear on a fresh marketplace install. Component CLIs still link normally. | Upgrade or reinstall the marketplace plugin, then start a new Codex session so bootstrap relinks bins. Verify with `npx lazycodex-ai doctor`; use `npx lazycodex-ai ` only as a temporary workaround. | | `sg` pending / offline | The ast-grep provisioning entry appears in the degraded list and the `ast-grep` skill cannot find `sg` yet — the first download is still running, or it failed while offline. | Start another session (bootstrap retries automatically), or install ast-grep yourself and/or set `OMO_AST_GREP_SG_PATH=/path/to/sg`. Verify with `npx lazycodex-ai doctor`. | | Proxy limitation | Binary downloads fail behind an HTTP(S) proxy. The logged error says it plainly: the bootstrap downloader "does not tunnel through HTTP(S) proxies in v1; the download was attempted directly." | Run one session on a direct connection, or provide `sg` via `OMO_AST_GREP_SG_PATH`/`PATH`. Verify with `npx lazycodex-ai doctor`. | | OpenCode Windows proxy preinstall | OpenCode starts before OMO loads, shows only default agents, or logs `fetch() proxy.url must be a non-empty string` while trying to install `oh-my-openagent@latest`. | Set `HTTP_PROXY`/`HTTPS_PROXY` for the shell that launches OpenCode, then preinstall into OpenCode's Windows config prefix: `npm install oh-my-openagent@latest --prefix "%APPDATA%\\opencode"`. Restart OpenCode and run `bunx oh-my-openagent doctor --json`. | **Windows status.** On native Windows the marketplace bootstrap runs through a PowerShell 5.1-compatible `bootstrap.ps1`: it provisions the pinned Node LTS zip when `node` is absent, prepares Git Bash the same way the npx installer does, and writes its transcript to `ps-bootstrap.log` in the plugin data dir (degraded lines look like `degraded component=node reason=... hint=npx lazycodex-ai doctor`). Windows provisioning is shipped with static test coverage; real-device validation is still tracked separately in [code-yeongyu/lazycodex#52](https://github.com/code-yeongyu/lazycodex/issues/52). Do not treat static coverage as proof that a physical Windows install was exercised. ### A note on direct install If you insist on running the Ultimate installer yourself: ```bash 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`. If you already used Bun global install or update and Bun reports blocked lifecycle scripts, inspect them before trusting anything: ```bash bun pm -g untrusted ``` Do not run a blanket trust command. Trust only packages you recognize from this install path, such as `oh-my-openagent`, legacy `oh-my-opencode`, or `@code-yeongyu/comment-checker`, then rerun the supported `bunx oh-my-openagent install` or `npx lazycodex-ai doctor` check. ### Senpi edition (beta): `omo` via npm `omo-ai` The senpi-native edition ships as the npm package `omo-ai` and installs a single command, `omo`, which launches the pinned senpi release with the full OMO extension loaded. No settings edits, no plugin registration, no extra setup. It is beta-channel only. The tag is mandatory: ```bash npm i omo-ai@beta omo ``` A bare `npm i omo-ai` fails with ETARGET on purpose; every published version is a prerelease, so the default channel never resolves. See the [omo-ai publishing runbook](../reference/omo-ai-publishing.md) for the mechanism. **Where omo keeps its state.** The senpi edition stores everything flat under `~/.omo` (`settings.json`, `auth.json`, `models.json`, `sessions/`, `themes/`, `prompts/`), alongside the files the other omo harnesses already keep there. On first run, an existing `~/.senpi/agent` is copied forward once: caches and logs are skipped, a `.migrated-from-senpi` marker is written, and the original directory is left untouched. That copy is a snapshot, not a link, so a standalone senpi install keeps working and the two products hold independent state from then on. Set `OMO_CODING_AGENT_DIR` to override the location; the legacy `SENPI_*` and `PI_*` variables are still read when the `OMO_*` one is unset. **Upgrade order on older machines.** If the machine still has oh-my-openagent/oh-my-opencode 4.19.4 or earlier installed globally, that package owns a global `omo` bin and the install above fails with EEXIST. Upgrade or uninstall the old package first, then install `omo-ai@beta`. ### First run: `omo setup` `omo setup` is the onboarding command for the senpi edition. It replaces the old manual "configure OmO/senpi" guidance; there's nothing to hand-edit anymore. It runs in three stages: 1. **Detect (read-only).** Scans your other coding-agent installs for provider credentials: senpi's agent dir (`SENPI_CODING_AGENT_DIR`, else `~/.senpi/agent`), opencode (`~/.local/share/opencode/auth.json`, XDG-aware), oh-my-pi (`~/.omp/agent/agent.db`), and gajae-code (`~/.gjc/agent/agent.db`). It reports, per harness, whether it's installed and which provider ids have credentials of which type. Credential values are never printed. The oh-my-pi and gajae-code databases are opened read-only. 2. **Import (consent-gated).** Only after you confirm (interactively, or with `--yes`; `--dry-run` previews without writing), compatible API-key credentials are imported into senpi's auth store. Existing senpi entries are never overwritten, and only providers senpi actually knows are imported. OAuth entries are reported but never imported. Source stores are never written; imports go to senpi's `auth.json` only, atomically and with a timestamped backup. 3. **Model report.** Prints a provider/model availability summary pointing at the [agent-model matching guide](./agent-model-matching.md), plus a ready-to-paste config snippet for any custom-endpoint providers it found. Report only; setup never writes model config for you. ## 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: > > ```bash > 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, help them install the requested edition, verify the setup, and configure model providers. 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 or Both, ask: > "Codex works best for autonomous agent installs when it can run without repeated permission prompts: `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, and `network_access = "enabled"`. This is recommended for OMO/LazyCodex. Should I configure Codex that way?" Map their answer to: | User says | Use | |-----------|-----| | Yes | `--codex-autonomous` | | No | `--no-codex-autonomous` | **If the user picked Codex only**, skip the rest of Step 0 after this autonomous-permissions question — 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 OpenAI routes; Hephaestus prefers GPT-5.6 Sol and Momus prefers GPT-5.6 Terra when available, both falling back to GPT-5.6 Sol) - **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.2, Kimi K3/K2.7, MiniMax M2.7/M3) - **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 have a Bailian Coding Plan subscription?** - **yes** -> `--bailian-coding-plan=yes` - **no** -> `--bailian-coding-plan=no` (default) 10. **Do you have a MiniMax CN Coding Plan subscription (`minimaxi.com`)?** - **yes** -> `--minimax-cn-coding-plan=yes` - **no** -> `--minimax-cn-coding-plan=no` (default) 11. **Do you have a MiniMax Coding Plan subscription (`minimax.io`)?** - **yes** -> `--minimax-coding-plan=yes` - **no** -> `--minimax-coding-plan=no` (default) 12. **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: ```bash 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.4.0`. #### For platform `codex` or `both` Check Codex CLI is installed: ```bash 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. On native Windows Codex installs, Git Bash is also required. The installer checks `OMO_CODEX_GIT_BASH_PATH`, standard Git for Windows locations, and PATH; if discovery fails, run: ```powershell winget install --id Git.Git -e --source winget where bash ``` For a custom Git Bash location, set `OMO_CODEX_GIT_BASH_PATH`: ```cmd setx OMO_CODEX_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe" ``` ```powershell $env:OMO_CODEX_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe" ``` ### Step 2: Run the installer Run with the platform flag and the subscription flags you collected in Step 0: ```bash bunx oh-my-openagent install \ --no-tui \ --platform= \ [--claude=] \ [--gemini=] \ [--copilot=] \ [--openai=] \ [--opencode-zen=] \ [--zai-coding-plan=] \ [--opencode-go=] \ [--kimi-for-coding=] \ [--bailian-coding-plan=] \ [--minimax-cn-coding-plan=] \ [--minimax-coding-plan=] \ [--vercel-ai-gateway=] \ [--codex-autonomous|--no-codex-autonomous] \ [--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. `--codex-autonomous` only has an effect when the selected platform includes Codex. **Examples:** - OpenCode + Claude Max20 + ChatGPT + Gemini: ```bash bunx oh-my-openagent install --no-tui --platform=opencode --claude=max20 --openai=yes --gemini=yes --copilot=no ``` - Codex only with recommended autonomous permissions: ```bash npx lazycodex-ai install --no-tui --codex-autonomous ``` - Both harnesses with Claude only: ```bash bunx oh-my-openagent install --no-tui --platform=both --claude=yes --gemini=no --copilot=no --codex-autonomous ``` - OpenCode + Z.ai for Librarian: ```bash bunx oh-my-openagent install --no-tui --platform=opencode --claude=yes --gemini=no --copilot=no --zai-coding-plan=yes ``` - OpenCode Go subscriber, nothing else: ```bash bunx oh-my-openagent install --no-tui --platform=opencode --claude=no --openai=no --gemini=no --copilot=no --opencode-go=yes ``` **About the Codex bin names.** Both `lazycodex-ai` and `lazycodex` are shipped bin aliases for the Codex Light Node installer; `lazycodex` is also the GitHub repository identity that hosts the marketplace bundle. Neither invocation requires Bun. 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 the `[opencode]` block of `~/.omo/omo.jsonc` (legacy config files are migrated into the unified file first). | | `codex`, `both` | Copies `packages/omo-codex/plugin/` into `~/.codex/plugins/cache/sisyphuslabs/omo//`. Packaged `lazycodex-ai` installs use bundled component artifacts and run `npm ci --omit=dev` in the cache; source checkout installs may build the plugin first. Writes a local installed-marketplace snapshot under `~/.codex/.tmp/marketplaces/sisyphuslabs/` for marketplace metadata, and copies bundled agent TOMLs into `~/.codex/agents/` so role definitions survive cache or temporary snapshot cleanup. Symlinks component CLIs into `~/.local/bin` (or `$CODEX_LOCAL_BIN_DIR`). Computes SHA256 trusted-hashes for every hook and writes `[marketplaces.sisyphuslabs]` with local source `~/.codex/plugins/cache/sisyphuslabs`, `[plugins."omo@sisyphuslabs"]`, managed `[agents.*]`, `[features.multi_agent_v2] max_concurrent_threads_per_session = 1000`, and `[hooks.state."omo@sisyphuslabs:..."]` blocks into `~/.codex/config.toml`. If a legacy `[features] multi_agent_v2 = false` shorthand exists, the installer converts it to `[features.multi_agent_v2] enabled = false` to keep the file valid while preserving the user's explicit disable. If `--codex-autonomous` is selected, also writes `approval_policy = "never"`, `sandbox_mode = "danger-full-access"`, `network_access = "enabled"`, and the matching `[notice]` warning suppressions. | Both halves are independent and idempotent — re-running is safe. ### Step 3: Verify #### Verify OpenCode plugin (skip if platform=codex) ```bash opencode --version # Should be 1.4.0 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 ``` For the OpenCode target, `doctor` runs eight registered checks: **System**, **Config**, **TUI Plugin**, **Deprecated Reasoning Keys**, **Tools**, **Models**, **Telemetry**, and **Team Mode**. The Codex target runs its own **Codex**, **Codex Components**, and **Codex Runtime Wrapper** checks. Exit code `0` means no check failed; exit code `1` means at least one check failed. Warnings alone still return `0`. #### Verify Codex CLI Light edition (skip if platform=opencode) ```bash # Plugin cache present? ls ~/.codex/plugins/cache/sisyphuslabs/omo/ # Marketplace source is the local built cache? grep -A4 'marketplaces.sisyphuslabs' ~/.codex/config.toml # Codex config has the plugin block? grep -A2 'omo@sisyphuslabs' ~/.codex/config.toml # If the user accepted autonomous mode, permission settings are present? grep -E 'approval_policy|sandbox_mode|network_access' ~/.codex/config.toml # Component binaries linked? ls ~/.local/bin/ | grep -E '^(omo-agent-toolkit|ulw|ulw-loop|omo-(comment-checker|git-bash-hook|lsp|rules|start-work-continuation|telemetry|ultrawork|ulw-loop))$' # Codex CLI sees the plugin? codex --help # On native Windows, Git Bash is discoverable? where bash ``` If any of these come back empty, re-run `npx lazycodex-ai install` — 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) ```bash 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`: ```json { "plugin": ["oh-my-openagent", "opencode-antigravity-auth@latest"] } ``` Then merge the full model configuration from the [opencode-antigravity-auth README](https://github.com/NoeFabris/opencode-antigravity-auth) 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 the `[opencode]` block of `~/.omo/omo.jsonc` (or a project `.omo/omo.jsonc`): ```json { "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.6-flash`, `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: ```bash 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. ##### Amazon Bedrock OpenCode owns Bedrock authentication. Configure Bedrock in `opencode.json` or through AWS environment variables first, then use Bedrock model IDs in OMO agent or category routing. ```json { "provider": { "amazon-bedrock": { "options": { "region": "us-east-1", "profile": "my-aws-profile" } } } } ``` For one-off launches, set the AWS credentials around OpenCode instead: ```bash AWS_PROFILE=my-aws-profile AWS_REGION=us-east-1 opencode ``` After OpenCode sees the provider, reference models with the OpenCode provider prefix: ```json { "agents": { "sisyphus": { "model": "amazon-bedrock/us.anthropic.claude-opus-5" }, "metis": { "model": "amazon-bedrock/us.anthropic.claude-sonnet-4-6" } } } ``` Use OpenCode's [Amazon Bedrock provider guide](https://opencode.ai/docs/providers/#amazon-bedrock) for model access, bearer tokens, named profiles, VPC endpoints, and custom inference profile ARNs. OMO does not run a separate Bedrock login flow during install. ##### 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.6-sol` | | **Explore** | `github-copilot/claude-haiku-4-5` | | **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.2` / `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.2` | | **visual-engineering** | `zai-coding-plan/glm-5.2` | | **unspecified-high** | `zai-coding-plan/glm-5.2` | | **Multimodal-Looker** | `zai-coding-plan/glm-4.6v` | ##### OpenCode Zen OpenCode Zen provides access to `opencode/` prefixed models including `opencode/claude-opus-5`, `opencode/gpt-5.6-sol`, `opencode/gpt-5-nano`, `opencode/glm-5.2`, `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-5` / `opencode-go/kimi-k3` | | **Oracle** | `opencode/gpt-5.6-sol` | | **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 5** | anthropic, github-copilot, opencode | Current best Opus. Dedicated per-agent prompt variants. | | **Claude Sonnet 5** | anthropic, github-copilot, opencode | Faster, cheaper. Good balance. | | **Claude Haiku 4.5** | anthropic, vercel | Fast and cheap. Good for quick tasks. | | **Kimi K3** | opencode-go, kimi-for-coding, moonshotai, opencode, vercel | Top recommended Kimi for Sisyphus when thinking-token cost is acceptable. | | **Kimi K2.7** | opencode-go, vercel | Restrained Kimi fallback for Claude-like orchestration paths. | | **Kimi K3 Free** | opencode | Free-tier Kimi. Rate-limited but functional. | | **GLM 5.2** | opencode-go, vercel | Claude-like behavior. Current OpenCode Go/Vercel fallback entry. | | **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.6 Sol** | openai, vercel | Preferred when available for Hephaestus and `ultrabrain`, with role-specific effort levels; first fallback for `deep`. | | **GPT-5.6 Terra** | openai, vercel | GPT-5.6 mid-tier. Default for Momus (high) and an optional balanced override elsewhere. | | **GPT-5.6 Luna** | openai, vercel | GPT-5.6 light tier. Default for the `unspecified-low` category (xhigh). | | **GPT-5.6 Sol override paths** | openai, github-copilot, opencode, vercel | Default for Oracle and the first GPT-5.6 Sol-family fallback for Hephaestus, Momus, `deep`, and `ultrabrain`. | | **GPT 5.6 Luna Fast** | openai, github-copilot, opencode, vercel | Fast + strong reasoning. Utility fallback after the Kimi high-speed quick default. | | **GPT-5-Nano** | opencode, vercel | 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.6 Flash** | google, github-copilot, opencode | Fast, good for doc search and light tasks. | | **MiniMax M3** | opencode-go, vercel | Latest MiniMax flagship. Primary utility fallback, ahead of M2.7. | | **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.7 Plus** | opencode-go | 1M context, high-speed reasoning. Default for Explore and Librarian when GPT 5.6 Luna 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. Manual override option — not in the default chains. | | **Claude Haiku 4.5** | anthropic, vercel | 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\|vercel/claude-opus-5 (max) → opencode-go\|kimi-for-coding\|moonshotai\|opencode\|vercel\|bailian-coding-plan\|moonshotai-cn\|firmware\|ollama-cloud\|aihubmix/kimi-k3 → openai\|github-copilot\|opencode\|vercel/gpt-5.6-sol (medium) → zai-coding-plan\|opencode\|bailian-coding-plan\|vercel/glm-5.2 → opencode/big-pickle | | **Metis** | Plan review | anthropic\|github-copilot\|opencode\|vercel/claude-opus-5 (high) → opencode-go\|kimi-for-coding\|moonshotai\|opencode\|vercel/kimi-k3 (low) | **Model-Flexible Agents** (fallback across Claude, GPT, and Claude-like models): Priority: **Claude > GPT > Claude-like models** | Agent | Role | Default Chain | Prompt behavior | | -------------- | ----------------- | ---------------------------------------------------------------------------------- | --------------- | | **Prometheus** | Strategic planner | anthropic\|github-copilot\|opencode\|vercel/claude-fable-5 (xhigh) → opencode-go\|kimi-for-coding\|moonshotai\|opencode\|vercel/kimi-k3 (max) | Single thin prompt backed by `ulw-plan`; model family does not switch the prompt | | **Atlas** | Todo orchestrator | anthropic\|github-copilot\|opencode\|vercel/claude-sonnet-5 → opencode-go\|vercel/kimi-k3 → openai\|github-copilot\|opencode\|vercel/gpt-5.6-sol (medium) → opencode-go\|vercel/minimax-m3 → minimax-coding-plan\|minimax-cn-coding-plan/MiniMax-M3 → opencode-go\|vercel/minimax-m2.7 | GPT-optimized todo management path | **GPT-Native Agents** (built for GPT, don't override to Claude): | Agent | Role | Default Chain | Notes | | -------------- | ---------------------- | -------------------------------------- | ------------------------------------------------------ | | **Hephaestus** | Deep autonomous worker | openai\|github-copilot\|vercel\|opencode/gpt-5.6-sol (medium) | "Codex on steroids." GPT-only chain. Requires GPT access. | | **Oracle** | Architecture/debugging | openai\|opencode\|vercel/gpt-5.6-sol (xhigh) → github-copilot/gpt-5.6-sol (high) → google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) → anthropic\|github-copilot\|opencode\|vercel/claude-opus-5 (max) → opencode-go\|vercel/glm-5.2 | High-IQ strategic backup. GPT preferred. | | **Momus** | High-accuracy reviewer | openai\|vercel/gpt-5.6-terra (high) → github-copilot/gpt-5.6-terra (high) → openai\|opencode\|vercel/gpt-5.6-sol (xhigh) → github-copilot/gpt-5.6-sol (high) → anthropic\|github-copilot\|opencode\|vercel/claude-opus-5 (max) → google\|github-copilot\|opencode\|vercel/gemini-3.1-pro (high) → opencode-go\|vercel/glm-5.2 | Verification agent. GPT preferred. | **Utility Agents** (speed over intelligence — do not "upgrade" them): | Agent | Role | Default Chain | | --------------------- | ------------------ | ---------------------------------------------------------------------- | | **Explore** | Fast codebase grep | openai/gpt-5.6-luna-fast → deepseek/deepseek-v4-flash (max) → opencode-go\|bailian-coding-plan/qwen3.7-plus → vercel/minimax-m2.7-highspeed → opencode-go\|vercel/minimax-m3 → minimax-coding-plan\|minimax-cn-coding-plan/MiniMax-M3 → opencode-go\|vercel/minimax-m2.7 → anthropic\|github-copilot\|vercel/claude-haiku-4-5 → openai\|vercel/gpt-5.4-nano | | **Librarian** | Docs/code search | (same chain as Explore) | | **Multimodal Looker** | Vision/screenshots | openai\|opencode\|vercel/gpt-5.6-sol (low) → opencode-go\|vercel/kimi-k3 → zai-coding-plan\|vercel/glm-4.6v → openai\|github-copilot\|opencode\|vercel/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: plan quality comes from making the plan **"Decision Complete"**: it must leave ZERO decisions to the implementer. Prometheus now uses one thin prompt backed by `ulw-plan` for that behavior instead of maintaining separate model-family prompt files. Atlas still has model-family-specific prompt behavior. Prometheus does not switch prompts when its model changes; the fallback chain changes capacity, cost, and availability, not the prompt text. #### Custom model configuration If the user wants to override which model an agent uses, edit the `[opencode]` block of `~/.omo/omo.jsonc` (or a project `.omo/omo.jsonc`): ```jsonc { "agents": { "sisyphus": { "model": "kimi-for-coding/kimi-k3" }, "prometheus": { "model": "openai/gpt-5.6-sol" }, // Uses the same ulw-plan-backed prompt }, } ``` **Lower-risk overrides** (compatible behavior): Sisyphus Opus → Sonnet/Kimi K3/GLM 5.2; Prometheus Opus → GPT-5.6 Sol (same prompt, different model); Atlas Kimi K3 → Sonnet/GPT-5.6 Sol (auto-switch). **GLM 5.2 fallback:** GLM 5.2 uses the GLM-5.2-calibrated Sisyphus prompt because its model ID is recognized as GLM. The automatic Sisyphus chain includes the `glm-5.2` literal explicitly. It still has less maintainer validation than Claude or Kimi. **Dangerous overrides** (no prompt support): Sisyphus → unsupported GPT models (the supported GPT paths cover 5.4, 5.5, and 5.6 Sol); Hephaestus → Claude (built for Codex); Explore → Opus (massive cost waste); Librarian → Opus (same). #### Optional: community model-management tools The independently maintained, experimental [oh-my-openagent VS Code extension](https://github.com/andersou/oh-my-openagent-vscode-extension) can edit user-level model assignments. It is a third-party configuration frontend, not an OMO runtime component; the OMO project does not maintain or support it, and compatibility is not guaranteed. Use external tools only with the canonical `[opencode]` fields described in [Configuration](../reference/configuration.md). Check which file the tool changed: a nearer project `.omo/omo.jsonc` overrides user-level settings. After using an external UI to change models: 1. Review the generated JSONC before restarting OpenCode. 2. Run `bunx oh-my-openagent doctor --verbose` to inspect its diagnostic model-resolution view. This does not replace checking nearer project config or runtime registration and model-matching rules. 3. Keep provider credentials and API keys in the provider auth flow or environment, not in shared project config. If an external tool shows a model that OMO later skips, the source of truth is still the model-matching and registration logic in this repository. Use the [Agent Model Matching](./agent-model-matching.md) guide to check whether the selected model family is supported for that agent. #### 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 mode`, `team-mode`, `team_mode`, or `teammode` | Ultimate | Forces `team_*` tools orchestration (requires `team_mode.enabled`); bare `team` does not trigger it | | `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 | |---------|:--------:|---------| | `/start-work` | Ultimate | Spawn Prometheus to interview the user and build a plan, then execute | | `/goal` | Ultimate | Set, show, pause, resume, or clear a persistent thread goal that auto-continues on idle until done | | `/stop-continuation` | Ultimate | Stop todo continuation, clear the active Goal, and clear boulder state | | `/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 | | `/init-deep` | Ultimate | Generate hierarchical AGENTS.md knowledge base (skill-backed slash command) | | `/hyperplan` | Ultimate | Direct invocation of hyperplan skill | #### Agents (11) — Ultimate only All 11 OpenCode discipline agents are part of the Ultimate edition. The Light edition does not ship this OpenCode agent registry; it ships separate Codex-native agent roles and the `teammode` component instead. Sisyphus delegates to the Ultimate agents below; 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 OpenCode skills load automatically when their description matches your task. The user does not need to invoke them by name. This OpenCode skill system is **Ultimate-only**; Light uses Codex-native plugin skills, including the script-driven `teammode` skill, rather than the OpenCode skill loader. | Skill | Editions | When it triggers | |-------|:--------:|------------------| | `playwright` | Ultimate | Browser automation | | `git-master` | Ultimate | Atomic commits, rebases, history search | | `frontend` | Ultimate | UI/UX implementation work | | `review-work` | Ultimate | Post-implementation code review | | `$omo:remove-ai-slops` | Ultimate | Cleaning AI-generated code smells | | `team-mode` | Ultimate | Loaded only when `team_mode.enabled` | Add custom skills under `.opencode/skills//SKILL.md` (project scope) or `~/.config/opencode/skills//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 5.** 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`](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//` - **Codex marketplace snapshot:** `~/.codex/.tmp/marketplaces/sisyphuslabs/` (local marketplace metadata and bundled source snapshot) - **User-linked component binaries:** `lazycodex-executor-verify`, `omo-comment-checker`, `omo-git-bash-hook`, `omo-lsp`, `omo-rules`, `omo-start-work-continuation`, `omo-telemetry`, `omo-ulw-loop`, `omo-ultrawork`, `ulw`, and `ulw-loop` in `~/.local/bin` (or under `$CODEX_LOCAL_BIN_DIR` if set). Other components, including `codegraph` and `teammode`, run through plugin MCP, hook, skill, or script surfaces rather than user-linked executables. The top-level `omo-agent-toolkit` command belongs to the shared oh-my-openagent launcher, not a Codex component. - **Codex agent roles:** `~/.codex/agents/{lazycodex-clone-fidelity-reviewer,lazycodex-code-reviewer,lazycodex-executor,lazycodex-gate-reviewer,lazycodex-qa-executor,lazycodex-worker-low,lazycodex-worker-medium,lazycodex-worker-high,explorer,librarian,metis,momus,plan}.toml` copied from the bundled plugin snapshot, so they keep resolving when Codex prunes old plugin-cache versions or temporary marketplace state - **Codex config edits:** `~/.codex/config.toml` gained `[features] plugins = true`, `[features] plugin_hooks = true`, `[features.multi_agent_v2] max_concurrent_threads_per_session = 1000`, `[marketplaces.sisyphuslabs]` pointing at `~/.codex/plugins/cache/sisyphuslabs`, `[plugins."omo@sisyphuslabs"]`, plugin MCP policy blocks, SHA256-pinned `[hooks.state."omo@sisyphuslabs:..."]` entries, and optionally autonomous permission settings if accepted. If the installer cannot resolve a CodeGraph-compatible Node runtime, it writes the `codegraph` MCP policy as disabled while leaving `omo@sisyphuslabs` enabled. #### The 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 | | `git-bash` | TypeScript + MCP | `PreToolUse` (`Bash`), `PostCompact`, MCP server | On Windows, exposes `git_bash`; reminds Codex before the first shell-like call and again after compaction | | `codegraph` | TypeScript + MCP | `SessionStart`, `PostToolUse`, MCP server | Provisions and wraps CodeGraph, initializes project indexes, and exposes its MCP tools | | `lazycodex-executor-verify` | TypeScript | `SubagentStop` | Requires evidence receipts from LazyCodex implementation workers before accepting completion | | `lsp` | TypeScript + MCP | MCP server + post-edit hooks | Exposes LSP diagnostics, navigation, symbols, rename via MCP | | `teammode` | TypeScript + skill | `PostToolUse` plus script-driven skill | Coordinates Codex-native agents or app threads with durable team state and thread-title guidance | | `ultrawork` | TypeScript | `UserPromptSubmit` keyword detector | Detects `ulw`/`ultrawork` keyword; the installer links bundled Codex agent TOMLs into `$CODEX_HOME/agents` | | `ulw-loop` | TypeScript | `UserPromptSubmit`, `PreToolUse`, `Stop` | Multi-goal orchestration with evidence audit trail, spawn guards, and Stop-hook auto-resume via `.omo/ulw-loop/` | | `start-work-continuation` | TypeScript | `Stop`, `SubagentStop` | Continues `.omo/boulder.json` start-work plans when Codex pauses at a stop boundary | | `telemetry` | TypeScript | `SessionStart` | Emits anonymous daily active telemetry when enabled | #### Coexistence with OpenCode The Codex CLI Light edition and the OpenCode plugin can run side-by-side. All harnesses read the unified `omo.jsonc` surface through harness-specific `[opencode]`, `[senpi]`, and `[codex]` views, while runtime state and model selection remain harness-specific. Each emits its own daily telemetry event. Compatibility note: LazyCodex is the Codex-platform OmO install path for `oh-my-openagent`. The bundled Codex-native subagents in `~/.codex/agents` are expected. Do not enable duplicate Codex-layer OmO/LazyCodex installs in a single `CODEX_HOME`; keep one `omo@sisyphuslabs` Codex plugin source active there. If the setup looks confused, run `npx lazycodex-ai doctor` before deleting cache or config state. #### Codex troubleshooting | Symptom | Fix | |---------|-----| | `codex --help` does not list the omo plugin | Re-run `npx lazycodex-ai install` (idempotent — hook hashes are recomputed) | | `command not found: omo-rules` or `command not found: omo-agent-toolkit` | 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"]` | | `MCP client for codegraph failed to start` | Re-run `npx lazycodex-ai install` with a CodeGraph-compatible Node runtime on `PATH`, or set `CODEGRAPH_NODE_BIN` to one. The installer disables only the `codegraph` MCP policy when the local runtime is unsupported; the rest of OMO remains enabled. | | `Ignoring malformed agent role definition: agents.*.config_file must point to an existing file` | Re-run `npx lazycodex-ai install`. The installer repairs stale managed `[agents.*]` entries and recreates `~/.codex/agents/*.toml`. | | `agents.max_threads cannot be set when multi_agent_v2 is enabled` in one project | Re-run `npx lazycodex-ai install` from that project. The installer repairs project-local `.codex/config.toml` layers, creates `.backup-` files for changed configs, and leaves user-authored `.codex` artifacts in place. | | `SessionStart hook (failed)` / `UserPromptSubmit hook (failed)` with `MODULE_NOT_FOUND` for `components/*/dist/cli.js` | Re-run the installer so the cached plugin is rebuilt with component `dist/` files. If the cache was manually edited, remove `~/.codex/plugins/cache/sisyphuslabs` first. | | `SessionStart hook (failed)` / `UserPromptSubmit hook (failed)` with only `hook exited with code 1` after install | Re-run `npx lazycodex-ai install`, then start a fresh Codex session or restart the Codex app. If the same hook fails again in the fresh session, inspect the saved hook output to identify the component command before deleting cache state. | | 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: ```jsonc // ~/.omo/omo.jsonc "[opencode]" block OR /.omo/omo.jsonc "[opencode]" block { "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 /.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 `/.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`](team-mode.md). ### Step 9: Advanced configuration #### Config file precedence ``` Project layers (nearest wins): /.omo/omo.json[c] ↓ merged onto User layer: ~/.omo/omo.json[c] ↓ resolved per harness, later wins Shared base → [opencode] block → profiles. → profiles..[opencode] ↓ applied once at the end Defaults ``` Merge rules: - Plain objects: deep merged recursively (prototype-pollution safe) - Scalars and arrays: override replaces base value - `mcp_env_allowlist`: **user-layer only** for security; project layers cannot extend it - Profile activation: `OMO_PROFILE` > `OCX_PROFILE` > `OPENCODE_CONFIG_DIR` tail `profiles/` > none Schema autocomplete in your editor: ```json "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/omo.schema.json" ``` #### Turning features off Every agent, hook, skill, MCP, command, and tool is configurable via `disabled_*` arrays: ```jsonc { "disabled_agents": ["multimodal-looker"], "disabled_hooks": ["goal", "keyword-detector"], "disabled_skills": ["playwright-cli"], "disabled_mcps": ["grep_app"], "disabled_commands": ["hyperplan"], "disabled_tools": ["interactive_bash"] } ``` #### Environment variables | Variable | Effect | |----------|--------| | `OMO_INVOCATION_NAME` | Overrides detected bin name (`oh-my-opencode`, `omo-agent-toolkit`, `lazycodex-ai`, etc.). Used by shared wrapper packages to route `lazycodex-ai` invocations to the Node installer path. | | `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-agent-toolkit 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 `packages/omo-opencode/src/openclaw/` for the full reference. ### Step 10: Maintenance | Command | Purpose | |---------|---------| | `bunx oh-my-openagent doctor` | Run 8 OpenCode checks (System / Config / TUI Plugin / Deprecated Reasoning Keys / Tools / Models / Telemetry / Team Mode), or the separate Codex target checks | | `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 ` | Authenticate with an MCP server using OAuth | | `bunx oh-my-openagent mcp oauth logout ` | Remove stored OAuth tokens for an MCP server | | `bunx oh-my-openagent mcp oauth status [server-name]` | Show OAuth token status for one or all servers | | `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 ` | 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 | `omo_daily_active` | Plugin load (`plugin_loaded`) + `run` CLI (`run_started`) | | Codex CLI Light edition | `omo_codex_daily_active` | Installer (`install_completed`) + Codex `SessionStart` hook (`session_start`) | Opt-out: ```bash # 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. The main plugin can also opt out through config: ```jsonc { "telemetry": false } ``` See [Privacy Policy](../legal/privacy-policy.md) and [Terms of Service](../legal/terms-of-service.md). ## Uninstall ### Remove the OpenCode plugin ```bash # 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 the unified config and any leftover legacy plugin config files (optional) rm -f ~/.omo/omo.jsonc ~/.omo/omo.json \ ~/.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 .omo/omo.jsonc .omo/omo.json \ .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 ```bash npx lazycodex-ai uninstall # backward-compatible alias: npx lazycodex-ai cleanup omo-agent-toolkit uninstall --platform=codex # backward-compatible alias: omo-agent-toolkit cleanup --platform=codex ``` The uninstall command removes the managed `~/.codex/plugins/cache/sisyphuslabs` and `~/.codex/.tmp/marketplaces/sisyphuslabs` trees, strips `sisyphuslabs` / legacy LazyCodex marketplace, plugin, hook-state, and managed agent blocks from `~/.codex/config.toml` after writing a timestamped backup, and removes managed agent TOML files from `~/.codex/agents/`, including orphaned files whose install manifest is already gone. If a workspace still has old project-local Codex state, run `npx lazycodex-ai uninstall --project ` or run it from that workspace. The command repairs only the known project-local Codex config conflict and reports legacy `.codex` artifact paths; it does not delete project-owned files automatically. ## 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 configuration lives in the unified `omo.jsonc`; legacy `oh-my-openagent.json[c]` / `oh-my-opencode.json[c]` files are imported once by the migration engine and no longer read at runtime. If `doctor` warns about the legacy package name, update your `opencode.json` plugin entry. --- ## File: docs/guide/overview.md # What Is Oh My OpenAgent? Oh My OpenAgent is a multi-model agent orchestration harness for OpenCode. It transforms a single AI agent into a coordinated development team that actually ships code. Not locked to Claude. Not locked to OpenAI. Not locked to anyone. Just better results, cheaper models, real orchestration. --- ## Quick Start ### Installation Paste this into your 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 ``` Or read the full [Installation Guide](./installation.md) for manual setup, provider authentication, and troubleshooting. ### Your First Task Once installed, just type: ``` ultrawork ``` That's it. The agent figures everything out — explores your codebase, researches patterns, implements the feature, verifies with diagnostics. Keeps working until done. Want more control? Press **Tab** to enter [Prometheus mode](./orchestration.md) for interview-based planning, then run `/start-work` for full orchestration. --- ## The Philosophy: Breaking Free We used to call this "Claude Code on steroids." That was wrong. This isn't about making Claude Code better. It's about breaking free from the idea that one model, one provider, one way of working is enough. Anthropic wants you locked in. OpenAI wants you locked in. Everyone wants you locked in. Oh My OpenAgent doesn't play that game. It orchestrates across models, picking the right brain for the right job. Opus 5 for orchestration and visual work. GPT-5.6 Sol for deep reasoning. Kimi K3 and GLM 5.2 as visual fallbacks. Kimi high-speed for quick tasks. All working together, automatically. --- ## How It Works: Agent Orchestration Instead of one agent doing everything, Oh My OpenAgent uses **specialized agents that delegate to each other** based on task type. **The Architecture:** ``` User Request ↓ [IntentGate] — Classifies what you actually want ↓ [Sisyphus] — Main orchestrator, plans and delegates ↓ ├─→ [Prometheus] — Strategic planning (interview mode) ├─→ [Atlas] — Todo orchestration and execution ├─→ [Oracle] — Architecture consultation ├─→ [Librarian] — Documentation/code search ├─→ [Explore] — Fast codebase grep └─→ [Category-based agents] — Specialized by task type ``` When Sisyphus delegates to a subagent, it doesn't pick a model name. It picks a **category** — `visual-engineering`, `ultrabrain`, `deep`, `artistry`, `quick`, `unspecified-low`, `unspecified-high`, `writing`. The category automatically maps to the right model. You touch nothing. For a deep dive into how agents collaborate, see the [Orchestration System Guide](./orchestration.md). --- ## Meet the Agents ### Sisyphus: The Discipline Agent Named after the Greek myth. He rolls the boulder every day. Never stops. Never gives up. Sisyphus is your main orchestrator. He plans, delegates to specialists, and drives tasks to completion with aggressive parallel execution. He doesn't stop halfway. He doesn't get distracted. He finishes. **Recommended models:** - **Claude Opus 5** / **Opus 5** — Best overall experience. Sisyphus was built with Claude-optimized prompts. - **Kimi K3** — Strongest Kimi for Sisyphus. Recommended when you can accept its thinking-token cost; the K3 prompt is calibrated to stop overthinking and keep work moving. - **Kimi K2.7** — Restrained, outcome-first Kimi fallback for Claude-like orchestration paths. - **GLM 5.2** — Solid option, especially via OpenCode Go. Sisyphus uses a GLM-5.2-calibrated prompt and the automatic chain includes `glm-5.2` explicitly, but current evidence is still lighter than Claude/Kimi maintainer validation. Sisyphus works best on Claude Opus 5, Kimi K3/K2.7, and GLM 5.2. GPT-5.4 has its own prompt, while GPT-5.5 and GPT-5.6 Sol share a model-aware GPT-native prompt family. Hephaestus remains the recommended GPT-5.6 agent because [issue #6074](https://github.com/code-yeongyu/oh-my-openagent/issues/6074) tracks Sisyphus over-orchestration on bounded work. ### Hephaestus: The Legitimate Craftsman Named with intentional irony. Anthropic blocked OpenCode from using their API because of this project. So the team built an autonomous GPT-native agent instead. Hephaestus prefers GPT-5.6 Sol at medium effort through OpenAI or Vercel, then falls back to GPT-5.6 Sol at medium effort across OpenAI, GitHub Copilot, OpenCode, or Vercel. Give him a goal, not a recipe. He explores the codebase, researches patterns, and executes end-to-end without hand-holding. Use Hephaestus when you need deep architectural reasoning, complex debugging across many files, or cross-domain knowledge synthesis. Switch to him explicitly when the work benefits from a GPT-native autonomous agent. **Why this beats vanilla Codex CLI:** - **Multi-model orchestration.** Pure Codex is single-model. OmO routes different tasks to different models automatically. Opus 5 for orchestration and visual work. GPT-5.6 Sol for deep reasoning. Kimi high-speed for quick tasks. The right brain for the right job. - **Background agents.** Fire 5+ agents in parallel. Something Codex simply cannot do. While one agent writes code, another researches patterns, another checks documentation. Like a real dev team. - **Category system.** Tasks are routed by intent, not model name. `visual-engineering` starts with Claude Opus 5 max, then Kimi K3 and GLM 5.2. `ultrabrain` prefers GPT-5.6 Sol xhigh, while `deep` uses GPT-5.6 Sol medium. `artistry` starts with Claude Fable 5, `quick` with Kimi high-speed, `unspecified-low` with Grok 4.6, and both `unspecified-high` and `writing` with Kimi K3. No manual juggling. - **Accumulated wisdom.** Subagents learn from previous results. Conventions discovered in task 1 are passed to task 5. Mistakes made early aren't repeated. The system gets smarter as it works. ### Prometheus: The Strategic Planner Prometheus interviews you like a real engineer. Asks clarifying questions. Identifies scope and ambiguities. Builds a detailed plan before a single line of code is touched. Press **Tab** to enter Prometheus mode, or type `@plan "your task"` from Sisyphus. ### Atlas: The Conductor Atlas executes Prometheus plans. Distributes tasks to specialized subagents. Accumulates learnings across tasks. Verifies completion independently. Run `/start-work` to activate Atlas on your latest plan. ### Oracle: The Consultant Read-only high-IQ consultant for architecture decisions and complex debugging. Consult Oracle when facing unfamiliar patterns, security concerns, or multi-system tradeoffs. ### Supporting Cast - **Metis** — Gap analyzer. Catches what Prometheus missed before plans are finalized. - **Momus** — Ruthless reviewer. Validates plans against clarity, verification, and context criteria. - **Explore** — Fast codebase grep. Uses speed-focused models for pattern discovery. - **Librarian** — Documentation and OSS code search. Stays current on library APIs and best practices. - **Multimodal Looker** — Vision and screenshot analysis. --- ## Working Modes ### Ultrawork Mode: For the Lazy Type `ultrawork` or just `ulw`. That's it. The agent figures everything out. Explores your codebase. Researches patterns. Implements the feature. Verifies with diagnostics. Keeps working until done. This is the "just do it" mode. Full automatic. You don't have to think deep because the agent thinks deep for you. ### Prometheus Mode: For the Precise Press **Tab** to enter Prometheus mode. Prometheus interviews you like a real engineer. Asks clarifying questions. Identifies scope and ambiguities. Builds a detailed plan before a single line of code is touched. Then run `/start-work` and Atlas takes over. Tasks are distributed to specialized subagents. Each completion is verified independently. Learnings accumulate across tasks. Progress tracks across sessions. Use Prometheus for multi-day projects, critical production changes, complex refactoring, or when you want a documented decision trail. --- ## Agent Model Matching Different agents work best with different models. Oh My OpenAgent automatically assigns optimal models, but you can customize everything. ### Default Configuration Models are auto-configured at install time. The interactive installer asks which providers you have, then generates optimal model assignments for each agent and category. At runtime, fallback chains ensure work continues even if your preferred provider is down. Each agent has a provider priority chain. The system tries providers in order until it finds an available model. ### Custom Model Configuration You can override specific agents or categories in your config: ```jsonc { "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/dev/assets/omo.schema.json", "agents": { // Main orchestrator: Claude Opus or Kimi K3 work best "sisyphus": { "model": "kimi-for-coding/kimi-k3", "ultrawork": { "model": "anthropic/claude-opus-5", "variant": "max" }, }, // Research agents: cheaper models are fine "librarian": { "model": "google/gemini-3.6-flash" }, "explore": { "model": "github-copilot/grok-code-fast-1" }, // Architecture consultation: GPT or Claude Opus "oracle": { "model": "openai/gpt-5.6-sol", "variant": "high" }, }, "categories": { // Frontend/UI work: Opus 5, then Kimi K3 and GLM 5.2 "visual-engineering": { "model": "anthropic/claude-opus-5", "variant": "max", }, // Hard logic and architecture: GPT-5.6 Sol xhigh "ultrabrain": { "model": "openai/gpt-5.6-sol", "variant": "xhigh" }, // Autonomous research and execution "deep": { "model": "openai/gpt-5.6-sol", "variant": "medium" }, // Creative and design work "artistry": { "model": "anthropic/claude-fable-5", "variant": "xhigh" }, // Quick tasks: fast and cheap "quick": { "model": "kimi-for-coding/kimi-for-coding-highspeed" }, // Low-effort fallback: GPT-5.6 Luna "unspecified-low": { "model": "xai/grok-4.6", "variant": "xhigh" }, // High-effort fallback: Kimi K3, then Opus 5 "unspecified-high": { "model": "kimi-for-coding/kimi-k3", "variant": "max" }, // Prose and documentation "writing": { "model": "kimi-for-coding/kimi-k3", "variant": "low" }, }, } ``` ### Model Families **Claude-like models** (instruction-following, structured output): - Claude Opus 5, Claude Haiku 4.5 - Kimi K3 — behaves very similarly to Claude - GLM 5.2 — Claude-like behavior, good for broad tasks **GPT models** (explicit reasoning, principle-driven): - GPT-5.6 Sol — preferred for Hephaestus and `ultrabrain`; the `deep` category uses it at medium effort - GPT-5.6 Terra — balanced mid-tier; preferred for Momus (high) and available as an explicit override elsewhere - Grok 4.6 — default for the `unspecified-low` category (xhigh) - GPT-5.6 Sol override paths — deep coding powerhouse, default for Oracle and the first GPT fallback for GPT-5.6-native roles - GPT 5.6 Luna Fast — fast and cheap utility fallback after the Kimi high-speed quick default **Different-behavior models**: - Gemini 3.1 Pro — visual-capable explicit override for providers that expose it; not the built-in `visual-engineering` default - MiniMax M3 / M2.7 / M2.7-highspeed — fast and smart for utility tasks - Grok Code Fast 1 — optimized for code grep/search See the [Agent-Model Matching Guide](./agent-model-matching.md) for complete details on which models work best for each agent, safe vs dangerous overrides, and provider priority chains. --- ## Why It's Better Than Pure Claude Code Claude Code is good. But it's a single agent running a single model doing everything alone. Oh My OpenAgent turns that into a coordinated team: **Parallel execution.** Claude Code processes one thing at a time. OmO fires background agents in parallel — research, implementation, and verification happening simultaneously. Like having 5 engineers instead of 1. **Hash-anchored edits.** Claude Code's edit tool fails when the model can't reproduce lines exactly. OmO's `LINE#ID` content hashing validates every edit before applying. Grok Code Fast 1 went from 6.7% to 68.3% success rate just from this change. **IntentGate.** Claude Code takes your prompt and runs. OmO uses regex detectors for explicit mode keywords: `ultrawork`/`ulw`, the Team Mode spellings, `hyperplan`, and the adjacent hyperplan-ultrawork combo. Matching text injects the corresponding mode prompt. **LSP + AST tools.** Workspace-level rename, go-to-definition, find-references, pre-build diagnostics, AST-aware code rewrites. IDE precision that vanilla Claude Code doesn't have. **Skills with embedded MCPs.** Each skill brings its own MCP servers, scoped to the task. Context window stays clean instead of bloating with every tool. **Discipline enforcement.** Todo enforcer yanks idle agents back to work. Comment checker strips AI slop. Goal is opt-in: `goal.enabled` and `goal.auto_start` both default to `false`. When enabled and started, it holds a persistent per-session objective and re-injects a continuation prompt on idle until a completion audit confirms the work is done. **The fundamental advantage.** Models have different temperaments. Claude thinks deeply. GPT reasons architecturally. Gemini visualizes. Haiku moves fast. Single-model tools force you to pick one personality for all tasks. Oh My OpenAgent leverages them all, routing by task type. This isn't a temporary hack — it's the only architecture that makes sense as models specialize further. The gap between multi-model orchestration and single-model limitation widens every month. We're betting on that future. --- ## IntentGate IntentGate is a regex-based mode keyword injector. It detects `ultrawork` or `ulw`, `team mode`/`team-mode`/`team_mode`/`teammode`, `hyperplan`, and the adjacent hyperplan-ultrawork combo, then adds the matching mode instructions. It does not semantically classify requests as research, implementation, investigation, or fixes. Prompts without those explicit mode keywords continue without IntentGate mode injection. --- ## What's Next - **[Installation Guide](./installation.md)** — Complete setup instructions, provider authentication, and troubleshooting - **[Orchestration Guide](./orchestration.md)** — Deep dive into agent collaboration, planning with Prometheus, and execution with Atlas - **[Agent-Model Matching Guide](./agent-model-matching.md)** — Which models work best for each agent and how to customize - **[Team Mode Guide](./team-mode.md)** — Parallel multi-agent coordination (OFF by default); 12 `team_*` tools, shared mailbox, shared task list, optional tmux layout - **[Configuration Reference](../reference/configuration.md)** — Full config options with examples - **[Features Reference](../reference/features.md)** — Complete feature documentation - **[Manifesto](../manifesto.md)** — Philosophy behind the project --- **Ready to start?** Type `ultrawork` and see what a coordinated AI team can do. ## 2. Official Technical Reference & Guides (code-yeongyu/code-yeongyu.github.io) # plainwhite Simplistic jekyll portfolio-style theme for writers. **Demo**: [thelehhman.com](https://thelehhman.com) ## Installation on Github Pages Add this line to your site's `_config.yml`: ```yaml remote_theme: thelehhman/plainwhite-jekyll ``` ## Installation Add this line to your Jekyll site's `Gemfile`: ```ruby gem "plainwhite" ``` And add this line to your Jekyll site's `_config.yml`: ```yaml theme: plainwhite ``` And then execute: $ bundle Or install it yourself as: $ gem install plainwhite ## Usage The "plainwhite" key in _config.yml is used to customize the theme data. ```yaml plainwhite: name: Adam Denisov tagline: Developer. Designer date_format: "%b %-d, %Y" social_links: twitter: thelehhman github: thelehhman linkedIn: in/thelehhman # format: locale/username ``` **Updating Placeholder Image** The placeholder portfolio image can be replaced by the desired image by placing it as `assets/portfolio.png` in your jekyll website. **Comments (Disqus)** Comments on posts can be enabled by specifying your disqus_shortname under plainwhite in `_config.yml`. For example, ```yaml plainwhite: disqus_shortname: games ``` **Google Analytics** It can be enabled by specifying your analytics id under plainwhite in `_config.yml` ```yaml plainwhite: analytics_id: '< YOUR ID >' ``` **Excerpts** Excerpts can be enabled by adding the following line to your `_config.yml` ```yaml show_excerpts: true ``` **Layouts** - Home - Page - Post ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/thelehhman/plainwhite-jekyll. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. ## Development To set up your environment to develop this theme, run `bundle install`. Your theme is setup just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal. When your theme is released, only the files in `_layouts`, `_includes`, `_sass` and `assets` tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in `plainwhite.gemspec` accordingly. ## License The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).