omc

omc — Claude-first topology-aware router for oh-my-claudecode

When to use this skill

The user wants Claude Code–native orchestration through OMC / oh-my-claudecode
The user needs to choose between the marketplace plugin, the omc shell CLI, or a local checkout / --plugin-dir workflow
The user asks about /team, /autopilot, /ralph, /ultrawork, /ultraqa, omc team, omc ask, omc setup, omc update, hooks, HUD, or OMC state behavior
The user asks how Claude workflows such as /team, /autopilot, /ultrawork, or /ultraqa map to Codex/OMX or Gemini/Antigravity/OMA
The user is hitting duplicate installs, plugin-dir confusion, worktree/state collisions, setup drift, or HUD / rate-limit / resume trouble
The user really wants a Claude-first runtime owner, not jeo, ralphmode, omx, ohmg, or browser-review skills

Instructions

Step 1: Identify the install topology before the packet

Before suggesting commands, identify which OMC topology the operator is actually using:

marketplace-plugin — Claude Code plugin / slash-skill surface installed from the marketplace
shell-cli — npm-installed omc command for shell-side setup, tmux workers, or provider asks
local-plugin-dir — local checkout / --plugin-dir / OMC_PLUGIN_ROOT workflow
mixed-or-unknown — overlapping plugin + CLI + local checkout, duplicate commands, or unclear setup state

If the topology is mixed-or-unknown, prefer recovery and topology clarification before recommending more commands.

Step 2: Pick one request packet

After topology is clear enough, classify the actual job into one packet:

install-topology — install, first-run setup, or local-checkout / plugin-dir decisions
in-session-runtime — choose the right slash skill inside Claude Code
terminal-runtime — choose the right omc ... shell command
recovery-and-update — fix duplicate installs, setup drift, worktree/state trouble, HUD/hooks, or resume issues
cross-runtime-parity — map Claude slash workflows to OMX or OMA without pretending the runtimes are identical
boundary-and-route-out — the request really belongs to jeo, ralphmode, plannotator, browser-review skills, or another runtime

Lead with the topology and packet mentally, then give only the commands that fit that combination.

Step 3: Tell the operator which surface they are on

OMC has two real runtime surfaces. Do not flatten them.

A. Claude Code plugin / in-session surface

Use this when the user is already inside Claude Code and wants slash skills, hooks, HUD, or native team behavior.

Examples:

/team 3:executor "fix all TypeScript errors"
/autopilot "build a REST API for tasks"
/ralph "keep going until verified done"
/ultrawork "parallelize this cleanup"
/deep-interview "help me clarify the feature"

This surface owns:

slash skills
hooks and HUD behavior
native team orchestration inside Claude Code
in-session keywords like autopilot: or ralph:

B. Terminal CLI surface

Use this when the user wants shell-side setup, updates, provider consultation, tmux workers, or runtime management.

Examples:

omc setup
omc update
omc ask codex "review this patch"
omc team 2:codex "review auth flow"
omc team status review-auth-flow

This surface owns:

omc setup / omc update
omc ask
omc team tmux workers
shell-side runtime management

Important truth:

/team and omc team are different runtimes
/autopilot, /ralph, and /ultrawork are in-session skills, not normal omc CLI subcommands
the npm package name is oh-my-claude-sisyphus, not oh-my-claudecode

Step 4: Use the right topology + packet pair

Packet: install-topology

Use when the user needs installation, setup, or topology cleanup.

marketplace-plugin

Inside Claude Code:

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

Then run one setup entrypoint inside Claude Code:

setup omc

or:

/oh-my-claudecode:omc-setup

shell-cli

If they also want omc shell commands:

npm i -g oh-my-claude-sisyphus@latest

local-plugin-dir

Do not pretend the marketplace flow is enough. Point them to the plugin-dir / local-checkout path and the dedicated reference before improvising cleanup:

omc --plugin-dir <path> ...
OMC_PLUGIN_ROOT
omc setup --plugin-dir-mode
references/install-topology-and-recovery.md

mixed-or-unknown

Treat duplicate commands, duplicate slash skills, or unclear state as a recovery problem first. Do not stack more installs on top of an ambiguous topology.

Enable native teams in ~/.claude/settings.json when Claude-native teams are expected:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Packet: in-session-runtime

Use when the user wants the best Claude Code slash skill for the job.

Need	Use	Why
Shared in-session multi-agent work	`/team ...`	Canonical Claude-native team workflow
End-to-end build from a fuzzy request	`/autopilot ...` or `autopilot: ...`	Single lead agent, idea → implementation
Must keep going until verified done	`/ralph ...` or `ralph: ...`	Persistent execute → verify → fix loop
Burst parallel work	`/ultrawork ...` or `ulw ...`	High parallelism without full team overhead
Parallel QA / review burst	`/ultraqa ...` when installed	QA fan-out; route to OMX `$ultraqa` or OMA `/review` when the target runtime is not Claude
Requirements clarification first	`/deep-interview ...`	Clarify before planning or execution
Cross-model synthesis	`ccg: ...` when upstream/runtime supports it	Advisory synthesis path

Pick one truthful recommendation plus at most 1 nearby alternative.

Packet: terminal-runtime

Use when the user wants the shell CLI rather than the in-session plugin surface.

Need	Use
Initial shell-side install/repair	`omc setup`
Refresh after updates	`omc update`
Provider consultation	`omc ask <provider> "..."`
tmux-based worker teams	`omc team <N>:<provider> "<task>"`
Team runtime status	`omc team status <session>`
Team runtime shutdown	`omc team shutdown <session>`

If the user says “team mode” but is already inside Claude Code, prefer /team. If the user says “team mode” and clearly wants shell/tmux workers, prefer omc team.

Packet: cross-runtime-parity

Use when the user wants Claude OMC workflows to be usable from Codex or Antigravity too. Read references/cross-runtime-workflow-map.md, then map by intent:

Claude / OMC	Codex / OMX	Gemini / Antigravity / OMA
`/team N:role "task"`	`$team N:role "task"` or `omx team N:role "task"`	`/orchestrate "task"` or `oma agent:parallel -i role:"task"`
`/autopilot "task"` or `autopilot: task`	`$autopilot "task"`; use `$deep-interview` first for vague requests or `$plan` → `$ralph` for stricter verification	`/plan "task"` → `/work`; use `/orchestrate` or `oma agent:parallel` only when explicit parallel lanes are needed
`/ultrawork "task"` / `ulw "task"`	`$ulw "task"` or `$ultrawork "task"`	`/ultrawork "task"` or `oma agent:parallel` for independent lanes
`/ultraqa "target"`	`$ultraqa "target"`	`/review "target"` or `/ultrawork "QA target"`; use `oma agent:parallel` for explicit QA lanes

Rules:

State the runtime boundary first: OMC uses .omc/, OMX uses .omx/, OMA keeps .agents/ canonical.
Treat /autopilot as an intent contract, not a universal command name: Codex owns $autopilot; OMA usually composes /plan and /work.
Do not claim Antigravity has Claude-style custom subagent spawning; use OMA CLI fallback when needed.
When the target is Codex-native, route operator details to omx.
When the target is Gemini/Antigravity portable harness work, route operator details to ohmg.

Packet: recovery-and-update

Use when the real job is repairing OMC.

Top recovery patterns:

Duplicate install / duplicate commands → inspect whether marketplace plugin, npm CLI, and local-checkout/plugin-dir installs are overlapping
Setup drift after upgrade → rerun the truthful setup/update path for the current topology (setup omc, /oh-my-claudecode:omc-setup, omc update, omc setup)
Local checkout not behaving like marketplace install → verify --plugin-dir, OMC_PLUGIN_ROOT, and plugin-dir mode instead of reinstalling blindly
Team mode not working → verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Worktree/state weirdness → inspect .omc/state/, worktree namespace behavior, and team/session names
HUD / rate-limit / ephemeral-environment trouble → treat it as environment/runtime recovery, not a mode-selection question

When the fix gets detailed, route to:

Packet: boundary-and-route-out

Do not force OMC when another skill owns the job better.

Route out when:

long-lived plan / execution ledger / resumable multi-skill loop → jeo
spec-first persistence method beyond OMC runtime detail → ralph
approval posture, trusted-folder / bypass policy, permission surface → ralphmode
plan review / approval gate → plannotator
fresh-session browser verification → browser-harness
running authenticated browser reuse → playwriter
exact rendered-UI critique / annotation handoff → agentation
Codex-first runtime orchestration → omx
Gemini / Antigravity portable harness adoption → ohmg
Claude workflow parity across Codex or Antigravity → use the cross-runtime-parity packet, then route to omx or ohmg for runtime-specific commands

Step 5: Keep the answer truthful about volatility

OMC is a fast-moving upstream project. Prefer:

topology truth first
current surface distinctions
current install/setup commands
current route-outs
reference docs for deeper operator detail

Avoid:

pretending all commands live on one surface
treating /team and omc team as interchangeable
promising that /ultraqa, $ultraqa, and OMA /review are the same implementation rather than mapped workflow intents
claiming there is a general omc autopilot CLI
stacking installs when duplicate-path symptoms suggest recovery first
absorbing browser review, approvals, or non-Claude runtime ownership into OMC

Examples

Example 1: Marketplace plugin install

User: "I want to install OMC and use team mode right inside Claude Code"

Response: Use the install-topology packet with marketplace-plugin topology. Give the plugin install path, then setup omc or /oh-my-claudecode:omc-setup, and mention CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 when native teams are expected.

Example 2: Local checkout / plugin-dir

User: "I'm modifying OMC on a local checkout, but because of the Claude plugin cache the old behavior keeps persisting. How should I point it to the plugin-dir?"

Response: Use the install-topology packet with local-plugin-dir topology. Point to --plugin-dir, OMC_PLUGIN_ROOT, and omc setup --plugin-dir-mode, then send the operator to the install-topology reference instead of treating this like a normal marketplace install.

Example 3: Shell-side worker team

User: "I want to attach two codex instances in the shell and run an auth flow review"

Response: Use the terminal-runtime packet. Recommend omc team 2:codex "review auth flow", keep the answer on the CLI runtime, and mention status/shutdown commands only if helpful.

Example 4: Long-loop orchestration boundary

User: "I want to run everything from planning to execution, verification, and resumption as one long-running loop"

Response: Use the boundary-and-route-out packet. Route to jeo as the long-loop coordination layer, and mention OMC only as the Claude-first runtime that jeo may compose with.

Example 5: Mixed duplicate install symptoms

User: "After the update, slash commands appear duplicated and the state is weird per worktree"

Response: Use the recovery-and-update packet with mixed-or-unknown topology. Tell them to inspect overlapping plugin/CLI/plugin-dir installs, then rerun the truthful setup/update path and inspect worktree/state behavior before choosing another mode.

Best practices

Name the topology before the packet when install or recovery is involved.
Prefer one recommended mode plus one nearby alternative, not a giant command dump.
Treat /team and omc team as related but different runtimes.
Keep the npm/package-name mismatch explicit: oh-my-claude-sisyphus provides the omc CLI.
Do not improvise over --plugin-dir or duplicate-install symptoms; route to the topology reference.
Route long-loop orchestration, approval posture, browser review, and other runtime ownership outward.
For Codex or Antigravity parity work, map the workflow intent and then hand off to omx or ohmg; do not write their runtime state into .omc/.
Use references for volatile operator detail; keep the front door focused on truthful routing.

About this skill