Guide — Understanding oh-my-openagent & omo-kit

This guide explains what oh-my-openagent does, why you need it, and how omo-kit generates the configuration for you. Jump-start your setup with sensible defaults — then tweak if needed.

What is oh-my-openagent?

The platform

Tool	What it is
OpenCode	The base terminal AI coding agent. A native terminal UI for AI-powered coding with 75+ LLM providers.
oMo (Oh My OpenAgent)	A plugin that transforms OpenCode's single agent into a coordinated team of 10+ specialized agents with intelligent model routing. Previously called `oh-my-opencode`.
OpenCode Go	A $10/month subscription providing reliable access to open coding models: DeepSeek V4, GLM-5.1, MiniMax M2.7, Qwen3.6. Uses `opencode-go/` prefix.
OpenCode Zen	Pay-as-you-go model provider. Curated, benchmarked models for coding agents. Uses `opencode/` (paid) and `zen/` (free) prefixes.

In short: OpenCode is the car. oMo is the racing team. OpenCode Go and Zen are different fuel stations.

Why model routing matters

Without oMo, OpenCode uses one model for everything — your code search uses the same expensive reasoning model as your architecture decisions. This is like sending a junior dev to design your database, or a senior architect to fix a typo.

With oMo, each agent role gets a model matched to its complexity — the orchestrator uses a reasoning model, code search uses a fast cheap model, and trivial fixes use the free tier.

What omo-kit generates

Running bunx omo-kit init creates four files in your project directory:

File	Purpose
`oh-my-openagent.json`	Agent routing table. Maps 10 agent roles and 8 task categories to specific models with thinking budgets and fallback chains.
`opencode.json`	Provider configuration. Tells OpenCode where oh-my-openagent.json lives and which model to use as default.
`tui.json`	Theme configuration. Terminal UI color scheme. Can be validated and regenerated via `omo-kit theme`.
`AGENTS.md`	Project conventions. Stack-specific instructions for AI coding agents: tooling, commands, commit style. Generated from stack templates.

~/my-project

$ omo-kit init --stack go --provider opencode-go --budget frugal -y ✓ Generated 4 files: oh-my-openagent.json opencode.json tui.json AGENTS.md

Or run interactively with omo-kit init — guided prompts for stack, providers, orchestrator, and budget. Flags: --stack, --provider, --budget, -y/--yes.

After generation, run omo-kit doctor --fix to validate and auto-correct.

Config walkthrough

Here's what each field in oh-my-openagent.json does, section by section.

disabled_skills & disabled_mcps

Strips irrelevant capabilities for your tech stack. Backend languages don't need frontend testing tools:

Stack type	Stacks	Disabled skills	Disabled MCPs
Web / Frontend	astro, svelte, node	none	none
Backend / Systems	go, rust, python	`frontend-ui-ux`, `frontend-design`, `design-taste-frontend`	`browser`, `playwright`
Generic	generic	none	none

Generated from your chosen stack's profile during init. Override in the generated file if needed.

Agent roles

oMo defines 10 specialized agents. Each gets a model matched to its task:

Agent	Purpose	Model tier	Thinking
sisyphus	Main orchestrator. Plans, delegates, verifies.	Premium	—
oracle	Architecture & debugging consultant. Read-only.	Premium	—
prometheus	Strategic planner. Creates work plans before execution.	Premium	—
atlas	Master executor. Reads plans, delegates to specialists.	Premium	—
metis	Pre-planning analysis. Catches ambiguities.	Premium	—
momus	Plan reviewer. Quality assurance before implementation.	Medium	16K
explore	Codebase search & pattern discovery.	Medium	Disabled
librarian	External research: docs, OSS, web search.	Medium	Disabled
sisyphus-junior	Category task executor. Runs delegated work.	Medium	4K
multimodal-looker	Image/PDF analysis.	Medium	—

Note: Premium agents (sisyphus, oracle, prometheus, atlas, metis) omit the thinking field entirely. This is intentional — DeepSeek V4 Pro has a known bug where reasoning_content isn't preserved across multi-turn conversations. Use Ctrl+T in the TUI for manual reasoning on single-turn queries.

Each agent config looks like this:

oh-my-openagent.json → agents.sisyphus

{ "model": "opencode-go/deepseek-v4-pro", "textVerbosity": "low", "fallback_models": [ { "model": "opencode-go/glm-5.1" }, { "model": "opencode-go/minimax-m2.7" }, { "model": "opencode-go/minimax-m2.5-free" } ] }

Category routing

When agents delegate work, they pick a category — not a model name. The category maps to the right model:

Category	Use case	Model tier	Thinking
visual-engineering	UI/UX, CSS, design, animation	Premium	8K
ultrabrain	Hard logic, algorithms, architecture	Premium	—
deep	Autonomous end-to-end implementation	Premium	—
unspecified-high	Complex undefined tasks	Premium	—
artistry	Creative problem-solving, unconventional approaches	Medium	16K
writing	Documentation, READMEs, prose	Medium	—
quick	Trivial tasks — typos, single-file changes	Free	Disabled
unspecified-low	Low-effort undefined tasks	Free	Disabled

Fallback chains

Every premium agent has the same capability-ordered fallback chain. If the primary model fails, oMo tries the next one:

Fallback chain

1. opencode-go/deepseek-v4-pro ← 80.6% SWE-bench, 93.5% LiveCodeBench 2. opencode-go/glm-5.1 ← 58.4 SWE-Bench Pro (#1 globally) 3. opencode-go/minimax-m2.7 ← 56.22 SWE-Bench Pro, 100 tok/s 4. opencode-go/minimax-m2.5-free ← 80.2% SWE-bench Verified, free

The order is backed by public benchmarks, not vibes. GLM-5.1 sits first in fallback based on SWE-Bench Pro performance. MiniMax M2.7 follows with competitive benchmarks at lower cost. M2.5-free is the safety net — free, so it can't break the bank.

big-pickle transparency: big-pickle is an OpenCode Go free-tier model with no published benchmarks. It only activates if minimax-m2.5-free fails, so risk is minimal. It appears as the final fallback for free-tier categories (quick, unspecified-low, writing).

Thinking budgets

Not every task benefits from chain-of-thought reasoning. omo-kit applies a tiered thinking policy:

Agent / Category	Thinking	Budget	Why
momus	Enabled	16,000	Plan review needs deep reasoning
artistry (category)	Enabled	16,000	Creative work benefits from exploration
visual-engineering	Enabled	8,000	Visual/design tasks need spatial reasoning
sisyphus-junior	Enabled	4,000	Task execution benefits from light reasoning
sisyphus, oracle, prometheus, atlas, metis	Omitted	—	Avoids DeepSeek V4 Pro thinking bug
explore, librarian	Disabled	0	Code search gains nothing from thinking
quick, unspecified-low, writing	Disabled	0	Trivial tasks — thinking is wasted tokens

Budget tiers

During init, you pick one of three budget strategies. This affects which model pool each agent tier pulls from:

Tier	Premium agents	Medium agents	Free agents
generous	DeepSeek V4 Pro	GLM-5.1, MiniMax M2.7	MiniMax M2.5-free
frugal	GLM-5.1	MiniMax M2.7	MiniMax M2.5-free
free-only	MiniMax M2.5-free	MiniMax M2.5-free	MiniMax M2.5-free

Frugal is the recommended starting point — premium model for the orchestrator, medium/free for everything else.

Stack-specific behavior

omo-kit provides 7 tech stack templates. Each one changes what gets generated:

Stack	Type	Disabled skills	Disabled MCPs	Agent overrides
astro	Web SSR/static	—	—	—
generic	Any	—	—	—
go	Backend systems	frontend skills	browser, playwright	oracle 16K thinking
node	Fullstack JS/TS	—	—	—
python	Backend/data	frontend skills	browser, playwright	—
rust	Backend systems	frontend skills	browser, playwright	oracle 16K thinking
svelte	Frontend	—	—	—

Each stack also generates a tailored AGENTS.md with stack-specific tooling, commands, conventions, and commit style.

Doctor — validation

After generating configs, run omo-kit doctor to verify everything. Supports --fix for auto-correction and --verbose for detailed output.

$ omo-kit doctor --fix

$ omo-kit doctor --fix ── CWD — ~/my-project ── ✓ oh-my-openagent.json valid ✓ opencode.json valid ✓ tui.json valid ✓ AGENTS.md valid Fixable issues → fix $schema: srmdn/ → code-yeongyu/ → rename "provider" → "providers" 2 fixes applied. Re-run doctor to verify.

What it checks: file structure, required fields, key validation, JSON validity. Exits 0 if clean, 1 with diagnostics if issues found.

Fixable issues: tab indentation → spaces, legacy srmdn/ schema references → code-yeongyu/, singular provider key → providers, legacy filename oh-my-opencode.json → rename. Run with --fix --yes to auto-apply without confirmation, --verbose for per-file scan details.

Customization

omo-kit gives you a starting point. Common customizations:

Swap a model

oh-my-openagent.json

{ "agents": { "sisyphus": { "model": "anthropic/claude-opus-4-8", // ← changed from opencode-go/... "fallback_models": [ { "model": "openai/gpt-5.5" }, { "model": "gemini/gemini-3.1-pro" } ] } } }

Add thinking to an agent

oh-my-openagent.json

{ "agents": { "oracle": { "model": "anthropic/claude-opus-4-8", "thinking": { "type": "enabled", "budgetTokens": 32000 } // ← added } } }

Add a custom category

oh-my-openagent.json

{ "categories": { "my-custom-category": { "model": "anthropic/claude-sonnet-4-6", "textVerbosity": "low", "prompt_append": "Focus on security-first implementation." } } }

Use a custom theme

After running omo-kit theme generate, you have a ~/.config/opencode/themes/my-theme.json file. Tell OpenCode to use it:

tui.json

{ "theme": "my-theme", // ← change from "default" "showThinking": true }

The theme name must match the filename (without .json) in ~/.config/opencode/themes/. Restart OpenCode to see the change. Validate with omo-kit doctor before restarting.

Quick start

Install OpenCode — brew install opencode or opencode.ai/docs
Install oMo plugin — bunx omo-kit setup
Connect OpenCode Go — run /connect in OpenCode, select OpenCode Go, paste API key. Subscribe ($10/mo)
Generate config — bunx omo-kit init in your project root. For non-interactive setup: bunx omo-kit init --stack go --provider opencode-go --budget frugal -y
Validate — bunx omo-kit doctor
Restart OpenCode to load the new config

Troubleshooting

Problem	Likely cause	Fix
"Model not found"	Wrong provider prefix or model ID	Check provider list. Use exact model ID.
Agent uses wrong model	Config not loaded or wrong config location	Verify file at `~/.config/opencode/oh-my-openagent.json` and restart
Usage cap hit	Exceeded OpenCode Go $60/month limit	Fallback to `minimax-m2.5-free` is automatic. Or wait for reset.
Qwen models not appearing	Upstream Alibaba issue	Add a `"status": "beta"` override in `opencode.json` provider section
DeepSeek thinking error	Known bug: `reasoning_content` dropped across turns	Config already omits thinking on premium agents. Use `Ctrl+T` for manual single-turn.

Known bug: DeepSeek V4 Pro's thinking mode has an active issue where reasoning content isn't preserved across multi-turn conversations. Three PRs were closed without merge. omo-kit intentionally omits the thinking field from DeepSeek-backed agents. Use Ctrl+T in the OpenCode TUI to toggle reasoning for single-turn critical queries.