oh-my-claudecode (OMC) plugin: a multi-agent Claude Code guide

Running more than one Claude Code agent on a problem is what oh-my-claudecode, usually shortened to OMC, is built for. Below: what OMC adds, its main modes, an install that leaves your own instructions intact, what to do with the .omc folder it creates, and an honest view of when orchestration earns its token bill.

I keep OMC installed next to the ECC plugin and switch it on per project. The facts below come from the OMC repository and Anthropic’s Claude Code documentation as of November 2026. If you have not settled your base setup yet, the Claude Code setup guide comes first.

What OMC is

oh-my-claudecode is an MIT-licensed project created and led by Yeachan Heo, described on GitHub as “Teams-first Multi-agent orchestration for Claude Code”. It had around 40,000 stars in November 2026. The same author publishes oh-my-codex for the OpenAI Codex CLI, and OMC’s README credits everything-claude-code among its inspirations.

OMC has two surfaces, and they do different jobs:

Surface	Install	What you get
Claude Code plugin	/plugin marketplace commands	In-session skills such as /team, /autopilot, /ralph, plus hooks, agents and the HUD status line
Terminal CLI	npm i -g oh-my-claude-sisyphus@latest	The omc command: setup, omc team tmux workers, omc ask, session search, rate-limit waiting

The npm package keeps an older name, oh-my-claude-sisyphus, but installs both oh-my-claudecode and omc commands. The CLI alone does not give you the in-session skills.

Under the hood, the reference documentation lists 19 agents with model tiers, 84 skills, and 21 hook scripts across 11 Claude Code lifecycle events. Defaults route by cost: explore and writer on Haiku, executor, code-reviewer and security-reviewer on Sonnet, and planner, critic and analyst on Opus. One detail matters for context cost: during setup, plugin installs compact each skill’s description and keep the full instructions in a separate directory that OMC loads only when the skill runs.

The modes

These are the modes you will actually use. Each runs inside a Claude Code session unless marked as CLI.

Mode	Start it with	What it does
Team	/team 3:executor "fix all TypeScript errors"	Staged pipeline: team-plan, team-prd, team-exec, team-verify, then team-fix in a loop, using Claude Code’s native agent teams
omc team (CLI)	omc team 2:codex "review auth module"	Real claude, codex, gemini, agy, grok or cursor-agent processes in tmux panes, started on demand and closed when done
Autopilot	/autopilot "build a REST API"	One lead agent takes an idea to working code with little ceremony
Ralph	/ralph "refactor auth"	Persistence: keeps working until verification passes
Ralplan	/ralplan "plan this feature"	Iterative planning with structured deliberation
Execute	/execute "refactor auth"	Carries an approved task to verified code with verify and fix loops
Deep interview	/deep-interview "vague idea"	Socratic questions to pin down requirements before any code
Ask	/ask codex "review this patch"	Runs a local provider CLI and saves the answer under .omc/artifacts/ask/

To stop whatever is running, type cancelomc or stopomc. The README also gives a rule worth following: use only one primary loop authority per session. Claude Code’s own /goal, OMC’s Execute, Team and Verify all want to own “done”, and stacking them produces loops that fight each other.

Install it without losing your own setup

You need Claude Code and either a Claude Pro or Max subscription or an Anthropic API key. omc team and the rate-limit waiter also need tmux (brew install tmux on macOS; the README points Windows users to psmux).

Add the marketplace and install the plugin. The README warns to enter these one at a time, because pasting both lines at once fails:

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

/plugin install oh-my-claudecode

The marketplace registers under the name omc, so the full plugin ID you will see in claude plugin list is oh-my-claudecode@omc. If you want the CLI as well:

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

Team mode depends on Claude Code’s experimental agent teams, which are off by default. Turn them on in ~/.claude/settings.json:

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

Without it, OMC warns and falls back to non-team execution where it can. Be aware of a side effect Anthropic documents: with agent teams enabled, a subagent that Claude names launches as a teammate, so teams can form even when you did not ask for one.

To update a marketplace install, run /plugin marketplace update omc, then re-run setup. If anything breaks after an update, /omc-doctor checks dependencies, hooks, agents and skill registration.

Setup and your CLAUDE.md

This is the step to slow down on. OMC’s setup writes its own instructions into a CLAUDE.md, and you choose where:

• /oh-my-claudecode:omc-setup --local writes .claude/CLAUDE.md in the current project and leaves your global file alone. OMC’s reference calls this the recommended option.
• Global setup targets ~/.claude/CLAUDE.md, and its default is to overwrite it. If your file exists without OMC’s markers, setup asks a second question: overwrite (the option OMC marks as recommended), or keep your file and install OMC into ~/.claude/CLAUDE-omc.md, which only the omc launcher loads.

If you maintain your own global CLAUDE.md, and especially if you also run ECC’s rules, choose the preserve option or opt out entirely with this in ~/.claude/.omc-config.json:

{ "claudeMdEnabled": false }

With that set, omc install, omc update and global setup leave ~/.claude/CLAUDE.md untouched. Project-scoped --local setup still works. One more check: if your team commits .claude/, look at the generated .claude/CLAUDE.md before it goes into a pull request, because it changes how Claude behaves for everyone on the repository.

The .omc state folder belongs in .gitignore

OMC writes runtime state to .omc/ at the git top level by default:

• .omc/state/ and .omc/state/sessions/{sessionId}/ for mode state and recovery
• .omc/notepad.md and .omc/project-memory.json for notes and project memory
• .omc/plans/, .omc/research/, .omc/logs/, .omc/artifacts/, .omc/handoffs/ and .omc/ultragoal/
• .omc/skills/, the only part meant to be committed, for project skills you want to share

OMC’s own documentation warns that runtime state “can include prompts, transcripts, absolute paths, machine identifiers, and workflow history”. Treat it like logs: never commit it, and never attach it to an issue without cleaning it first.

Local setup inside a git repository seeds .git/info/exclude with an OMC block. That helps, but Git documents info/exclude as the place for patterns that do not need to be shared, and it is not committed. A colleague’s clone and your CI checkout never see it. Put the rule in the committed .gitignore too:

# oh-my-claudecode runtime state; keep shared project skills
.omc/*
!.omc/skills/
!.omc/skills/**

The /* matters. Git cannot re-include a file if a parent directory of that file is excluded, so a plain .omc/ line would make .omc/skills/ impossible to commit. If you never share OMC skills, .omc/ on its own is fine.

Two settings change where state lives:

• OMC_STATE_DIR moves state outside the repository to $OMC_STATE_DIR/{project-id}/, which survives worktree deletion. Shell profiles are not read by editors launched from the GUI, so OMC recommends setting it in the env block of ~/.claude/settings.json. Setting it does not migrate existing state.
• A .omc-workspace marker in a non-git parent folder makes several sibling repositories share one .omc/.

After sessions stop, OMC’s reference says it is safe to delete .omc/state/, .omc/logs/, .omc/artifacts/, .omc/research/ and .omc/ultragoal/. Plans in .omc/plans/ are ignored too, so move any plan you want to keep into a tracked docs folder.

When orchestration helps and when it wastes tokens

Anthropic’s agent teams documentation is direct about cost: teams “use significantly more tokens than a single session”, each teammate has its own context window, and usage scales with the number of active teammates. The same page says teams work best when teammates can operate independently, and that for “sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective.”

That gives a simple test: orchestrate only when the work splits into pieces that do not touch the same files and do not wait on each other.

Situation	Better choice
Review a pull request for security, performance and tests	/team with three reviewers, each on one lens
Bug with an unclear root cause	Team with competing hypotheses that try to disprove each other
New feature split cleanly into frontend, backend and tests	/team, with each teammate owning different files
Bug in one function or one file	Plain Claude Code session
Refactor that edits the same files in sequence	Single session, or /ralph with a clear done condition
Vague requirements	/deep-interview first; it is cheap next to building the wrong thing
A second opinion from another model	/ask codex instead of a full team

Anthropic suggests starting with three to five teammates and around five or six tasks per teammate. Three focused teammates often beat five scattered ones.

Where OMC spends tokens without asking

• Magic keywords. OMC’s keyword detector reads every prompt. Phrases such as “build me”, “I want a” and “end to end” start autopilot. “Don’t stop” and “until done” start ralph. “Code review”, “tdd” and “think hard” inject modes. Keywords in code blocks, URLs and file paths are ignored, but an ordinary sentence can still start an autonomous run. If you prefer explicit control, switch the detector off and use slash commands:

  export OMC_SKIP_HOOKS="keyword-detector"

• Persistence modes. Ralph and autopilot are enforced by a hook that blocks Claude Code’s Stop event until the work is verified. Give them a measurable definition of done, such as named tests passing, or they keep going.

• Accidental teams. With CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS on, ordinary delegation can create teammates. Set it to 0 when you do not need teams.

• Unmeasured savings claims. The README says smart model routing saves 30 to 50% on tokens. That is the project’s claim. Check it on your own work with the HUD’s showTokens element or omc session friction report --since 24h.

For a full stop, DISABLE_OMC=1 disables all OMC hooks for the session.

Running OMC alongside ECC

ECC and OMC overlap more than their descriptions suggest. Both register hooks on SessionStart, PreToolUse, PostToolUse, PreCompact and Stop. Both inject context when a session starts. Both have a learning or memory system: ECC’s continuous learning and instincts, OMC’s project memory, notepad and /skillify. Both ship agents called code-reviewer, security-reviewer and planner, kept apart only by their namespaces, ecc: and oh-my-claudecode:. OMC’s reference tells you to always use the oh-my-claudecode: prefix when delegating to its agents.

The way to keep them from fighting is to give each one a job:

Concern	Owner
Standards and conventions	Your CLAUDE.md plus ECC’s copied rules
Hard safety gates	ECC hooks such as config protection and GateGuard
Orchestration and persistence	OMC, started explicitly with slash commands
Memory across sessions	One system only. Disable the other’s hooks
Reviews	Name the agent you want, ecc:code-reviewer or oh-my-claudecode:code-reviewer

A setup that works:

1. Install ECC at user scope. The ECC plugin guide covers its hooks and rules.

2. Install OMC, then disable it at user scope and enable it only in the repositories where you orchestrate. Local scope overrides user scope:

   claude plugin disable oh-my-claudecode@omc --scope user
   claude plugin enable oh-my-claudecode@omc --scope local

3. Run /oh-my-claudecode:omc-setup --local in those repositories, or set claudeMdEnabled to false, so your global CLAUDE.md stays yours.

4. Set OMC_SKIP_HOOKS="keyword-detector" so a stray phrase does not start autopilot.

5. Pick one memory system. If you keep OMC’s, add ECC’s pre:observe and stop:evaluate-session to ECC_DISABLED_HOOKS.

6. Run claude plugin details on both plugins to see the always-on token cost each adds, and run /doctor prompt-audit after OMC writes its CLAUDE.md block, since its instructions and ECC’s rules now share your context.

7. Add the .omc/* block to .gitignore in every repository where OMC runs.

If you split work between Claude Code and Codex, the Claude Code vs Codex CLI comparison covers where each fits, and omc team N:codex is one way to put both on the same task.

OMC setup rules

• OMC is the oh-my-claudecode@omc plugin, with an optional omc CLI from the oh-my-claude-sisyphus npm package.
• Prefer --local setup, or set claudeMdEnabled: false, so OMC does not overwrite your global CLAUDE.md.
• Commit .omc/*, !.omc/skills/ and !.omc/skills/** to .gitignore. .git/info/exclude covers only your clone.
• Use Team for independent, parallel work: reviews, research, competing hypotheses, file-separated features. Use a single session for everything else.
• Switch off the keyword detector, give persistence modes a measurable done condition, and keep one loop and one memory system per session.
• Next to ECC, let ECC own standards and safety gates and let OMC own orchestration, enabled only where you need it.