oh-my-claudecode: multi-agent orchestration for Claude Code, installed as a plugin or an npm CLI

What oh-my-claudecode adds on top of Claude Code

Claude Code gives you one assistant in one session. oh-my-claudecode arranges several of them: a planner, an executor, and a QA stage that inspect each other's output. The README frames the pitch as "Multi-agent orchestration for Claude Code. Zero learning curve," and the tagline underneath is blunter: "Don't learn Claude Code. Just use OMC." That is the audience. Someone who wants the multi-agent pattern without building the coordination layer, the prompts, and the handoff rules themselves.

The npm package is named oh-my-claude-sisyphus, which is worth knowing before you go looking for a package called oh-my-claudecode and conclude it does not exist. The repository is TypeScript, MIT licensed, and its package.json exports a main entry plus a ./team subpath, so the orchestration code is importable as a library as well as usable through the binaries.

Two surfaces are exposed, and the README is explicit that they are different things. Terminal CLI commands run as omc ... from your shell. In-session skills run as /... inside a Claude Code session. The repository also ships a .claude-plugin directory and a .mcp.json, which is how the plugin and MCP server paths are wired. IDE integrations, per the project description, are only an optional way to reach Claude Code itself, not a separate OMC surface.

How the orchestration actually runs: autopilot, stages and workflow profiles

The central concept is autopilot. You give it a task in natural language and it moves through stages. The README's example is /autopilot "build a REST API for managing tasks", and the same thing can be typed in-session as autopilot: build a REST API for managing tasks.

Named stage profiles let you pick which stages run. They are selected only through /autopilot --workflow <name> <task>. A v1 profile contains exactly two fields, version and stages, and the admitted sequences are a closed set: [ralplan, execution], [ralplan, execution, ralph], [ralplan, execution, qa], and [ralplan, execution, ralph, qa]. That closure is a design decision, not an oversight. The ADR referenced in the README states that v1 intentionally excludes model fields or routing (stageModels), inline execution, dynamic commands, modes or state, arbitrary stages or plugins, and a separate custom-skill frontmatter parser. If your plan was per-stage model routing to control cost, this version does not do it.

Profiles live under autopilot.workflows in either .claude/omc.jsonc for a project or ~/.config/claude-omc/config.jsonc for a user. A project profile with the same name wholly replaces the user profile; profiles with different names coexist. Environment variables cannot define profiles. Profiles stay inside autopilot's existing state, cancel, resume, Stop and HUD lifecycle, and invocations without --workflow remain compatible, so adding profiles does not break older commands.

Installing oh-my-claudecode and running a first autopilot task

There are two install paths and they lead to different surfaces. The plugin path is what the README recommends for most Claude Code users. These are Claude Code slash commands, and the README warns that you must enter them one at a time because pasting both lines at once will fail.

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

Then, as a separate entry:

/plugin install oh-my-claudecode

If you want the terminal CLI instead, install the npm package globally. Note the package name, which differs from the repository name.

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

The README documents a known npm warning here: npm may print deprecated [email protected] during the CLI install. That comes from the upstream better-sqlite3 native-addon dependency, and the README states that [email protected] is still the latest published version, so there is no repo-side bump or override that removes it. It is tracked as issue #2913, and the warning by itself does not mean the CLI install failed.

Setup runs differently depending on which surface you installed. Inside a session it is a slash command; from the terminal it is the omc binary.

# Inside a Claude Code / OMC session
/omc-setup

# From your terminal
omc setup

Then run something. The README's first real task is a REST API, given either as a slash command or as a natural-language in-session shortcut.

/autopilot "build a REST API for managing tasks"

To use a named profile, pass it explicitly. This is the only admitted way to select one.

/autopilot --workflow plan-build-qa "build a REST API for managing tasks"

And the profile itself is a small JSONC block. The README's example uses plan-build-qa with three stages.

{
  "autopilot": {
    "workflows": {
      "plan-build-qa": {
        "version": 1,
        "stages": ["ralplan", "execution", "qa"]
      }
    }
  }
}

One setup detail catches people who use directory flags. If you run OMC via omc --plugin-dir <path> or claude --plugin-dir <path>, add --plugin-dir-mode to omc setup, or export OMC_PLUGIN_ROOT before running it, so the installer does not duplicate skills and agents the plugin already provides at runtime. The README points to a plugin directory flags section in docs/REFERENCE.md for the full decision matrix.

The Linux-only constraint on named autopilot profiles

This is the sharpest limitation in the documentation, and it is stated plainly. Named profiles currently require Linux with the flock utility. The reason is mechanical: their transcript evidence boundary uses Linux no-follow file-descriptor traversal, and their recoverable mutation lock uses kernel advisory locking. Neither is portable to a system without those primitives.

The consequence is well handled. Unsupported environments reject an explicit --workflow invocation before creating or changing autopilot state. So you get a refusal rather than a half-written profile. And legacy autopilot, the version without --workflow, remains available on those platforms. In other words, macOS and Windows users are not locked out of OMC; they are locked out of one feature that the project chose to build on Linux-specific guarantees rather than approximate elsewhere.

Whether that is the right trade is a judgement call. Building the evidence boundary on no-follow traversal is a defensible way to keep an agent from following a symlink out of the transcript it is supposed to read. The cost is a platform split that will surprise anyone who reads the quick start on a Mac, configures a profile in .claude/omc.jsonc, and only then discovers the requirement. The README does flag it, but it appears after the profile example rather than before it.

What OMC does not cover, and where a lighter tool fits

The README's own signposting is the most useful limitation section. It points Codex users to oh-my-codex, described as "the same orchestration experience for OpenAI Codex CLI." That is a different runtime, not a competing feature set, so it matters only if your team is not on Claude Code.

More interesting is the second pointer. The README asks whether you liked OmC but found it "a bit overkill," and directs you to gajae-code, which it describes as keeping Claude OAuth as-is while being faster, cheaper and simpler, with an SDK-based integration path built for OpenClaw, Hermes, Grokbot and similar agent runtimes. A project recommending a lighter alternative to itself is a real signal about where OMC sits. If your need is a single agent with a better prompt and a couple of hooks, the full stage machinery, the profile schema, the MCP bridge and the plugin-versus-CLI split are overhead you will pay for in setup time and in surface area to understand.

The other boundary is the one the project description draws itself: IDE integrations are only an optional way to reach Claude Code. OMC is not a VS Code extension and does not claim to be one. If your workflow lives in an editor panel, you are still going through Claude Code to get to OMC.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-08-28. The release history is dense around that date: v5.0.0 on 2026-08-24, then v5.0.1 and v5.0.2 both on 2026-08-28. Note that package.json declares version 5.4.0 while the most recent tagged release listed is v5.0.2, so the published npm package and the release tags do not move in lockstep. If version pinning matters to you, read the package version rather than the release name.

Upgrade cost is higher than a typical CLI, because the build pipeline is long. The build script chains TypeScript compilation with prompt-SSOT generation and verification, workflow stage prompt building, skill bridge building, MCP server building, bridge entry building, doc composition, prompt projections, the CLAUDE.md coordinator, the runtime CLI, the team server and the CLI. Several of those steps are generated artifacts. There is a prompt-ssot:check script, which implies prompt source-of-truth drift is a real failure mode the maintainers guard against. For a consumer installing from npm this is invisible. For anyone vendoring the repository or patching skills, it means a change to a prompt source propagates through generation steps you must rerun.

The licence is MIT, which permits commercial use, modification and redistribution with the licence and copyright notice preserved. That is a permission statement, not advice about your situation; if you are embedding OMC in a product, the obligations you carry are the ones your counsel reads out of the MIT text and the licences of the bundled dependencies, which include a native addon.

Reading the repository before you install

The top level is worth a scan because it tells you how much is generated versus hand-written. Alongside src, tests and docs you find agents/, commands/, hooks/, skills/, templates/, missions/, receipts/, inventory/, shellmark/, seminar/, benchmark/ and geobench/. The presence of both benchmark/ and benchmarks/, plus geobench/, suggests the project measures its own prompt and agent behavior rather than only shipping it.

That matters for evaluation. If you are deciding whether to adopt OMC, the prompts under agents/ and skills/ are the actual product surface, more than the TypeScript. The TypeScript wires them together; the prompts decide whether the planner produces plans you would accept and whether the QA stage catches anything. The README also links a migration guide at docs/MIGRATION.md, which is the document to read if you are coming from an earlier major version, given that v5.0.0 landed days before the current release.

For a project this size, the honest position is that the README documents the happy path well and the edge cases unevenly. The --plugin-dir-mode flag and the OMC_PLUGIN_ROOT variable are documented, but the README itself defers the full decision matrix to a section of docs/REFERENCE.md. Read that section before you install if you use plugin directories, because getting it wrong duplicates skills and agents rather than failing loudly.

Editorial conclusion

Adopt OMC if you already run Claude Code daily and want a repeatable plan, execute and QA loop without writing your own agent glue; the plugin install and /omc-setup take minutes. Skip it if you work on Windows or macOS and need named autopilot profiles, since those require Linux with flock, and skip it if you only wanted a lighter wrapper, because the README itself points to gajae-code for that. Before committing, verify the omc binary resolves after npm i -g oh-my-claude-sisyphus@latest, confirm whether you are on the plugin path or the CLI path (mixing them without --plugin-dir-mode duplicates skills), and check that your .claude/omc.jsonc profile names appear in omc's own state rather than only in the file.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes