oh-my-agent: A Specialist Team for the Coding Agent You Already Use

한국어 | 中文 | Português | 日本語 | Français | Español | Nederlands | Polski | Русский | Deutsch | Tiếng Việt | ภาษาไทย

oh-my-agent (oma) adds a team of specialists to the coding agent you already use: Claude Code, Codex CLI, Cursor, and 11 more. A planner breaks the work down, engineers build in parallel, a reviewer checks the result, and a debugger fixes root causes. It also does cited research, slide decks, videos and images. Most steps leave a file you can open, and in the long-running workflows a gate can send the agent back to work until your own test, lint or typecheck script passes.

Run this from your project root:

curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh | bash

Then run oma doctor and type /plan add user accounts with a settings page in your agent. Your first 5 minutes walks through it.

Watch the full video (35s)

What you get

Workflows are what you type (or just say). They call in roles, the specialists. Skills are the know-how: each role carries its own, and your agent loads the rest whenever a task needs them.

Install · First 5 minutes · The team · Which workflow? · Everything in the box · Works with · Verification · FAQ · Docs

Install

The script installs bun if it is missing, installs the oma command globally (bun install --global oh-my-agent, skipped when oma is already on your PATH), then starts the interactive setup. The global command matters: the hooks (keyword detection, the Stop gate) and several workflows call oma, and the hooks silently do nothing when they cannot find it. If you skip the script, install it yourself with bun install --global oh-my-agent (npm install --global oh-my-agent or brew install oh-my-agent also work).

Windows, or without the install script

# Windows (PowerShell)
irm https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.ps1 | iex

# Any OS with bun installed: the same setup, plus the global `oma` command
bun install --global oh-my-agent
oma

On Windows the installer hides Antigravity, Hermes, and Kimi, and the hook wrapper is a bash script. The default Aside browser MCP installs through bash, so deselect it if you have no bash.

The setup asks for your response language, which agent runtimes to wire up, capability providers, a browser MCP, a model preset, and a skill preset. Pick All for the skill preset if you are unsure: workflows are always installed, and several of them (/orchestrate, /work, /ultrawork, /ralph, /docs, /security) need skills that only All includes.

What the installer also does by default

• Installs bun (required). Tries uv, Serena (uv tool install), and CUE (brew install cue or winget), and continues with a warning if any of them fails.
• Pre-selects the Aside browser MCP in the interactive setup, and installs it with curl -fsSL https://releases.aside.com/install.sh | bash only if you keep it selected. Deselect it in the browser MCP step, or change it later with oma update mcp.
• Uses AgentMemory for semantic memory, which runs bun install -g @agentmemory/agentmemory and registers it as a login service (launchd, systemd user unit, or Windows scheduled task). Choose provider none or set OMA_NO_AGENTMEMORY=1 to skip it.
• Asks before linking skills into home-directory vendor folders (Antigravity, Hermes, Kimi). In $HOME without --global it asks for confirmation.
• Writes some files outside the project without asking: ~/.claude.json (marks the project as a trusted Claude Code workspace), ~/.serena/ (OMA context, answer-size floor, project registration), ~/.cursor/cli-config.json (turns off Cursor's commit attribution), ~/.grok/config.toml (telemetry), and ~/.gemini/antigravity-cli/ (HUD), each only for a vendor you selected.
• Writes telemetry opt-outs into vendor settings (Claude DISABLE_TELEMETRY=1, which also turns off Claude Code Remote Control; Gemini, Qwen, Codex, and Grok usage stats). Set telemetry: true to keep vendor defaults.
• Disables Qwen Code automatic memory saving by adding memory.enableManagedAutoMemory: false when the setting is absent. Explicit true or false preferences and other memory settings are preserved.
• Adds unset Claude Code settings to .claude/settings.json, including skipDangerousModePermissionPrompt: true, effortLevel: high, cleanupPeriodDays: 180, and env flags that turn off auto memory, adaptive thinking, error reporting, and built-in git instructions. Values you already set are kept.
• Adds a co-author trailer: Claude Code's commit attribution becomes Co-Authored-By: First Fluke and PRs get a "Generated with oh-my-agent" line. Set scm.co_author.enabled: false to turn this off.
• Installs a commit-msg guard in .githooks/ that rejects unlisted Co-authored-by addresses, and sets git config --local core.hooksPath .githooks when no other hooks are active. Set scm.co_author.enforce_hook: false to opt out.
• oma update updates the oma CLI in the background (auto_update_cli: false or OMA_SKIP_VERSION_CHECK=1 to stop it) and runs uv tool upgrade serena-agent --prerelease=allow (serena.auto_update: false).
• With Serena in the default bridge mode, the first agent session that starts a shared Serena server registers a cleanup timer that stops idle shared Serena servers every 5 minutes (launchd dev.oma.serena-daemon-gc, systemd user timer oma-serena-daemon-gc.timer, or Windows scheduled task OMA Serena Daemon GC). Set serena.mode: stdio to skip the shared server and its timer. oma uninstall does not remove the timer.
• Non-interactive runs (-y, OMA_YES=1, CI=true) use the All skill preset, model_preset: auto, and Python as the backend language. They select no browser MCP (and skip the Aside install script) unless mcp.devtools_browsers already lists one.

Skill presets

Of the named presets, only All includes coordination, orchestration, docs, security, refactor, explanation, recap, video, slide, and skill-creation (or pick them under Custom). Research and Content lack the skills behind /plan, /review, /debug, /architecture, and /brainstorm. See Workflows that need skills outside a preset.

Your first 5 minutes

1. Install with the command above.

2. Check the install:

   oma doctor
   

   You should see CLI Status (which agent CLIs are installed and signed in) and Skills Status (for example Skills (33/33 installed, 33 complete)). If oma is not found, open a new terminal (the installer may have just added ~/.bun/bin to your PATH) or run bun install --global oh-my-agent.

3. Open your agent in the project and ask for a plan:

   /plan add user accounts with a settings page
   

   Or just write "plan user accounts with a settings page": on runtimes with a prompt hook, the keyword starts the same workflow.

4. Check what you got. /plan runs in the current session. For work that spans several areas, like this one, it writes .agents/results/plan-.json and a tracker at docs/plans/work/-.md. A small, single-area request gets a direct recommendation instead of a plan file.

Stop there. You will know whether this is for you. When you want more, run /work or /orchestrate on the plan.

Meet the team

Your own agent leads the team. In /work, /orchestrate and /ultrawork it hands each job to the right specialist, which runs as its own subagent. /plan, /architecture and /docs run in your current session with that role's skill, and /review and /debug call in their specialist for large scopes. When a role is on another vendor's CLI, oma agent spawn runs it there.

The other three roles, and the skills without a role

The infra engineer (tf-infra-engineer) is told to ask before any destructive or production apply or destroy. The remaining skills (brainstorm, security, scm, dev-workflow, observability, explanation, recap, translation, coordination, orchestration, skill-creation, content and media) have no dedicated role. Your agent loads them itself, and for most of them the skill injector suggests the right one from your prompt.

How the team works together

 THINK   /brainstorm ......................... docs/plans/designs/-.md
 PLAN    /plan · /architecture ............... plan JSON, API contracts, ADR
 DESIGN  /design ............................. DESIGN.md + tokens
 BUILD   /work · /orchestrate · /ultrawork ... code + result- files, engineers in parallel
 CHECK   /review · /security · /debug ........ findings, security evidence, regression test
 SHIP    /scm · /docs ........................ Conventional Commits, doc fixes

Each step hands a file to the next. /brainstorm saves a design that /plan reads, and /plan writes a plan in which every task has an agent, dependencies, acceptance criteria and a check command. /orchestrate runs that plan (it loads the most recent plan-*.json, or writes one). /work and /ultrawork start by having the PM write their own plan. Skip any stage you don't need; every stage also works on its own.

Which workflow should run the team?

You don't need slash commands. On runtimes with a prompt hook, plain requests (keyword banks in up to 11 languages) can start most workflows: "review this PR" starts /review. Describing a whole app ("Build a TODO app with user authentication") suggests /orchestrate, and your agent decides whether to run it. Keywords inside code blocks are ignored.

/orchestrate, /work, /ultrawork and /ralph are persistent when you invoke them by name, as a slash command or in plain text ("ultrawork: add rate limiting"). The agent is then sent back to work when it tries to stop early (up to 5 times or 2 hours) until you say "workflow done". A loosely matching request only suggests them.

Measured, with caveats. In the benchmark (one prompt, Claude Code with five different add-on setups including plain, claude-opus-4-6, one build each), oma scored 80.6 against 70.7 for plain Claude Code, at 1.7x the cost ($4.04 vs $2.37) and 1.8x the time.

All 21 workflows

Trigger accuracy is measured, not assumed: oma verify triggers scores the detector against a labeled English and Korean corpus of 212 prompts, and CI fails above 10% false fires or 20% missed fires. Last measured: 0% missed-fire, 5.3% false-fire. Full reference: Workflows.

See it work

An illustrative /ultrawork session. The [OMA PERSISTENT MODE: ULTRAWORK] block is the exact format the Stop hook prints; the other lines are paraphrased:

you    /ultrawork add rate limiting to POST /login
agent  runs `oma goal set --gate test`
agent  PLAN writes .agents/results/plan-.json
agent  IMPL -> VERIFY -> REFINE -> SHIP  (each review runs in a fresh reviewer session)
agent  "Rate limiting added. All tests pass."
oma    [OMA PERSISTENT MODE: ULTRAWORK]
       Stop gate 'test' FAILED (reinforcement 1/5).
       Fix the failures below, then finish the workflow — the stop is allowed only when the gate passes.
       --- gate output (tail) ---
       FAIL  src/auth/login.test.ts > returns 429 after 5 attempts
       To abandon instead: delete .agents/state/ultrawork-state-.json or say "workflow done".
agent  fixes the limiter and stops again
oma    `test` exits 0: stop allowed, gate.passed appended to the session log

Afterwards, oma state list finds the session and oma state get (the ID state list prints) shows every gate event. Under /ralph, oma ralph verify --json also checks that the phases left their files behind (output trimmed):

{ "ok": false,
  "missing": [{ "id": "A3", "description": "a distinct QA agent ran (VERIFY phase)",
                "pattern": ".agents/state/memories/result-qa*.md or .agents/results/result-qa*.md",
                "status": "missing" }] }

Everything in the box

Plan and design: /brainstorm, /plan, /architecture, /design

Build: 7 domain skills, plus /stack-set to fit them to your stack

/stack-set reads your manifests and writes stack-specific references for the backend, frontend and mobile skills. In a monorepo, frontend, backend and mobile engineers are pointed at their workspace (pnpm, npm/yarn/bun workspaces, lerna, nx, turbo, mise.toml).

Review, fix and ship: /review, /security, /debug, refactor, /scm

Docs and knowledge: /deepinit, /docs, /explain, /recap, translation

Research: search, market, papers, academic writing

Content and media: /video, /convert, slides, images, voice

These pipelines report a missing source or vendor key instead of silently returning a thinner result.

Hooks that run without being asked

oma hook probe checks that oma's prompt hooks accept each runtime's hook input (it does not launch the runtime). Which hooks each runtime wires is in Host differences.

Parallel agents, sessions and dashboards

• oma agent spawn "" runs a role on Antigravity, Claude, Codex, Cursor, OpenCode, Qwen, Grok or Pi, with --isolation worktree and --fallback-vendors. oma agent parallel runs several at once.
• Add --read-only to require a vendor restriction before launch. Codex uses its read-only sandbox, Claude uses plan mode, and Pi excludes edit, write, bash, and powershell. Other CLIs require an explicit read_only_flag; missing, empty, or known conflicting flags stop dispatch. Custom flags declare support in your CLI or wrapper. Pi's tool exclusions do not restrict arbitrary extension or MCP tools; OMA does not add an operating-system sandbox.
• oma state list --all-projects and oma state get : sessions and every recorded event.
• oma dashboard terminal / oma dashboard web: live agent status (the web dashboard listens on 127.0.0.1 only). Dashboard guide.
• oma stats get (productivity metrics), oma retro (a git retrospective), oma recap --window 7d (what you did across AI tools).
• oma visualize --affected : which skills, workflows, agents and checks depend on the .agents/ files you changed.

Code intelligence, memory and MCP

Agents coordinate through plain files in .agents/state/, with no outside service. /tools turns MCP tools on or off in plain language. Details: Capability Providers.

Getting better over time

• oma skill eval measures a skill's lift over a baseline on held-out tasks. oma skill optimize proposes edits that raise it, and --apply keeps them (skill-eval guide).
• oma harness evolution enable --max-dispatches schedules a nightly cycle that turns failed runs into regression fixtures and applies skill improvements that pass evaluation as project overlays. Add --mode propose to only record them.
• oma emit exports the .agents/ source as an Agent Skills package, an Agent Plugins package, a Claude Code plugin marketplace, or AGENTS.md.

Config and safety rails

• One user-owned .agents/oma-config.yaml survives updates (only oma update --force resets it); private .local.yaml or .local.cue overlays can sit on top of it. language sets the response language.
• 13 project rules (backend, commit, database, debug, design, and more) load as native rules in Claude Code and Cursor, and are indexed in the managed AGENTS.md block written for Codex, Qwen Code and Pi.
• Updates keep config and migration backups in .agents/backup/; shipped skills and workflows are replaced in place, so keep local changes outside them. oma uninstall --dry-run shows what would be removed. first-fluke/oma-update-action@v1 runs oma update in CI and opens a PR.

All 33 skills

Works with

14 installer targets: Claude Code, Codex CLI, Cursor, Antigravity, Qwen Code, Grok, Kiro, Kimi, OpenCode, Pi, GitHub Copilot, Hermes, CommandCode, and ZCode. Wire a runtime you skipped with oma link . Runtimes differ in which hooks they offer; the full matrix is in Supported Agents.

• Orca IDE: OMA for Orca adds a sidebar panel and command-palette actions (Orca 1.4.197+ with experimental plugins).
• DeepSeek Harness: OMA for DeepSeek Harness connects OMA checks through a Cordis plugin. It needs oma on your PATH.

Runtime logos (installer targets plus Amp and DeepSeek Harness)

native = oma writes the runtime's own config files; adapter = oma also adds hook or agent shims. Amp reads .agents/skills/ by itself and is not an installer target.

Claude Code

native + adapter

Codex CLI

native + adapter

Antigravity

native SSOT

Cursor

native + adapter

Qwen Code

native dispatch

DeepSeek Harness

Cordis plugin

Pi

native-compatible

OpenCode

native-compatible

Amp

reads .agents/skills

GitHub Copilot

symlinked skills

Grok Build

native hooks

Kiro CLI

native hooks + agents

& more

Host differences: which runtimes get keyword detection and the Stop gate

Per-agent models

model_preset in .agents/oma-config.yaml chooses which model each agent role uses. The default, auto, follows the running runtime's own agent and model settings.

language: en
model_preset: auto   # auto | free | antigravity | claude | codex | cursor | kiro | mixed | qwen | 

# Optional per-agent overrides; they win over the preset
agents:
  backend: { model: openai/gpt-5.5, effort: high }

• mixed uses Claude for orchestrator, architecture, QA, PM, and docs, and Codex gpt-5.5 for implementation roles, so it needs both Claude Code and Codex CLI.
• free routes through a FreeLLMAPI gateway and needs FREELLM_API_KEY plus a running server.
• kiro is not in the installer menu; set it in the config file.
• oma doctor --profile prints the resolved model for each role.
• Full guide: Per-agent models

Verification, Not Narration

Agents narrate success. oh-my-agent checks the artifacts. See it work shows the Stop gate in action; here is every check oma runs, and what each one proves.

Every mechanism below except the prompted judge is mechanical: a command exits 0 or it doesn't, a file is on disk or it isn't. None of those asks an LLM whether the work "looks correct."

No session, no trail. The Stop hook records gate events under the OMA session opened when the persistent workflow started. Event writes are best-effort. If that session could not be created (stderr shows [oma] L1 session activation failed), a failing gate still blocks the stop, but no gate.failed line is written. Before you rely on the trail, or demo it, check that oma state list shows an active session; oma state get then shows its events.

Limits, details, and how the Stop hook decides

Limits to know:

• The Stop gate applies only to the persistent workflows (/orchestrate, /work, /ultrawork, /ralph). Without oma goal set --gate, it only re-prompts the agent to continue. /ultrawork tells the agent to set a gate when the project has a cheap check, but nothing enforces it. Run oma goal set --gate test yourself if you want to be sure; the other persistent workflows never set one.
• Only the typecheck, test, and lint keywords are accepted, and they run the package.json script of that name. No package.json, or no script with that name, means the gate is not run. Non-JS projects need a package.json wrapper script.
• The block is released and logged as failed after 5 reinforcements, after 2 hours, or when --budget-minutes runs out, so a permanently red gate cannot trap you.
• Budgets: session.quota_cap caps tokens, spawn count, and per-vendor tokens; the orchestrator refuses the next spawn when a dimension is exceeded.

Artifact gate. A missing artifact means the phase did not run, whatever the narration says. The refactor check also passes as skip-recorded when the session log records a REFINE skip reason.

Prompted judge. The /ralph workflow prompt tells the orchestrator to spawn the judge as a separate agent with fresh context, briefed on the criteria only (never on what the implementer claims it fixed), and to re-verify every criterion each iteration, including earlier PASSes, because fixing C2 is how C1 silently regresses. Nothing checks that the spawn happened: oma ralph verify gates the EXEC artifacts, not the judge, and a runtime that cannot spawn subagents is told to judge inline and record ralph.judge-inline-fallback. /ralph stops after 5 iterations with a partial report.

Event log. Find the session with oma state list and read it with oma state get . Each event is stamped with vendor and runtime session id. The file's location depends on OMA_HOME, OMA_STATE_HOME, OMA_PROFILE, and older project-local session folders, so don't hard-code it.

Per-agent checks. Types: backend, frontend, mobile, qa, debug, pm. The command exits 1 when any check fails; TODO/FIXME Comments and Inline Styles only warn.

• backend: Syntax, SQL Injection (raw SQL patterns), and Tests, from the commands in stack/stack.yaml. Without that file (generate it with /stack-set) they are skipped.
• frontend: the stack/stack.yaml syntax and test commands (under oma-frontend, or angular-developer when that skill is installed), or TypeScript (tsc --noEmit) and Frontend Tests (Vitest). Inline Styles and Any Types always run.
• mobile: the stack/stack.yaml syntax and test commands, or Flutter/Dart Analysis and Flutter Tests.
• debug: Python Tests (pytest through uv) or Frontend Tests (Vitest).
• pm: PM Plan (the plan file is valid JSON).
• qa: no mechanical checks.

flowchart TD
    S[Agent tries to stop] --> P{Persistent workflow active?}
    P -- no --> A[Stop allowed]
    P -- yes --> D{User or agent said workflow done?}
    D -- yes --> A
    D -- no --> R{Budget spent, state older than 2 h, or 5 blocks reached?}
    R -- yes --> F[Stop allowed, logged as gate.failed]
    R -- no --> G{Gate set and package.json script exists?}
    G -- no --> B1[Blocked: workflow still active]
    G -- yes --> X{Script exits 0 within 25 s?}
    X -- yes --> OK[Stop allowed, logged as gate.passed]
    X -- no --> B2[Blocked with output tail, logged as gate.failed]

FAQ

Do I need every skill?

No. See Skill presets; All is the safe default.

How do I know it is working?

oma doctor shows installed skills and warns when hooks can't find oma. During a persistent workflow, oma state list shows the active session and oma state get shows its gate events.

Does it cost more tokens?

Usually, yes. Skills load only when a task needs them, but multi-agent workflows and fresh-context reviews spend more. In the one-prompt benchmark, oma cost 1.7x plain Claude Code.

The Stop hook keeps blocking. How do I get out?

Say "workflow done" (or "workflow complete" / "workflow finished", or the equivalent in the other supported languages), or delete .agents/state/-state-.json. If you do neither, it releases on its own after 5 blocks or 2 hours.

How do I update or uninstall?

oma update refreshes skills, workflows, and hooks and keeps your config (--with-new-skills adds skills new in the release; oma update mcp re-chooses the browser MCP). oma uninstall --dry-run shows what would be removed; oma uninstall removes it and keeps oma-config.yaml, mcp.json, and skills you wrote. More fixes: Troubleshooting.

What does oh-my-agent leave to the model?

Planning and choosing the next step stay with your agent's model; oma has no fixed workflow graph. What oma enforces outside the model: tool guardrails (secret and search guards), budgets, retry and stop limits, an event log, and, when you set a gate, a stop that waits for your own checks to pass.

Learn More

• Docs site: guides, tutorials, and CLI reference. Start with Quick Start and Installation.
• Why oh-my-agent: when to choose it and the trade-offs
• Benchmark Report: how it compares with superpowers, ECC, and oh-my-claudecode on one prompt, with method, scores, screenshots, and caveats
• Supported Agents: support matrix across runtimes
• Detailed Documentation: technical spec and architecture
• Capability Providers: experimental Gortex and Honcho configuration, routing, and limits
• Skill Compatibility Matrix: native skill content, references, and response contracts in Claude and Codex

Like this project? Give it a star!

gh api --method PUT /user/starred/first-fluke/oh-my-agent

Try our optimized starter template: fullstack-starter

Star History

References

Research this builds on (7 papers)

• Li, X., Liu, Y., Chen, W., You, B., Di, Z., He, Y., Zheng, S., Choe, K. W., Sun, J., Wang, S., Tao, C., Li, B., Zhao, X., Geng, H., Wu, X., Zhou, J., Chen, X., Xing, H., Li, Y., … Song, D. (2026). SkillsBench: Benchmarking how well agent skills work across diverse tasks (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2602.12670
• Yu, G., & Wang, X. (2026). Knows: Agent-native structured research representations (Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.17309
• Liang, Q., Wang, H., Liang, Z., & Liu, Y. (2026). From skill text to skill structure: The scheduling-structural-logical representation for agent skills (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.24026
• Chen, C., Yu, Q., Gu, Y., Huang, Z., Li, H., Liu, H., Liu, S., Liu, J., Peng, D., Wang, J., Yan, Z., Meng, F., Qin, E., Che, C., & Hu, M. (2026). The scaling laws of skills in LLM agent systems (Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.16508
• Tang, L., Rashtchian, C., Ferng, C.-S., Tomkins, A., Juan, D.-C., & Vu, T. (2026). WikiSkill: Compiling agent experience into persistent knowledge for skill evolution [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2608.27454
• Huang, Z., Xu, J., Yang, Y., Gong, Z., Yang, Q., Tian, M., Wang, X., Lv, C., Gao, X., Dai, Q., Liu, B., Qiu, K., Yang, X., Chen, D., Zheng, X., & Luo, C. (2026). From raw experience to skill consumption: A systematic study of model-generated agent skills [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.23899
• Hong, D. B., Imani, A., & Ahmed, I. (2026). From anatomy to smells: An empirical study of SKILL.md in agent skills (Version 2) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2607.01456

License

MIT