# oh-my-claudecode ships under the name oh-my-claude-sisyphus, and its stage profiles need Linux flock

> oh-my-claudecode is a multi-agent orchestration layer for Claude Code, installable either as a Claude Code plugin or as a global npm CLI, and the project documents both surfaces separately. It is a good fit for teams who want named autopilot stage sequences, and a poor fit on macOS or Windows, where named profiles are refused outright because they depend on Linux file locking.

**Yeachan-Heo/oh-my-claudecode** — Teams-first Multi-agent orchestration for Claude Code. Use the Claude Code plugin or terminal CLI surfaces above; IDE integrations are only an optional way to access Claude Code itself.

- Repository: https://github.com/Yeachan-Heo/oh-my-claudecode
- Website: https://oh-my-claudecode.dev
- Stars: 39,408 · Forks: 3,525
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/yeachan-heo-oh-my-claudecode

## The npm package is oh-my-claude-sisyphus, and it installs three binaries

The mismatch between repository name and install name is the first thing to get right. The project lives at Yeachan-Heo/oh-my-claudecode and its homepage is oh-my-claudecode.dev, but the published package carries a different name:

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

The manifest settles it. The name field is oh-my-claude-sisyphus at version 5.5.0, type is module, and main points at dist/index.js with a second export at ./team for dist/team/index.js. The bin map installs three names: oh-my-claudecode and omc both resolve to bin/oh-my-claudecode.js, so they are the same entry point under two aliases, and omc-cli resolves to a different file, bridge/cli.cjs. Surfaces matter here too, because the project draws a line between terminal CLI commands you run as `omc ...` from a shell and in-session skills you run as `/...` inside a Claude Code session. The two are installed by different flows and the table of differences between them is long.

## The two plugin slash commands fail if you paste them together

The recommended path is the Claude Code plugin marketplace, and it comes as two commands:

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

```bash
/plugin install oh-my-claudecode
```

The instruction that carries the most weight sits directly above them: these are Claude Code slash commands and you must enter them one at a time, because pasting both lines at once will fail. That is a harness level constraint rather than a packaging bug, and it is the kind of detail that turns into a wasted afternoon when you trust your clipboard. Setup is a separate step, run either as /omc-setup inside a Claude Code or OMC session or as `omc setup` from your terminal. The first real workload then goes through /autopilot, for example /autopilot "build a REST API for managing tasks", or its natural language in session shortcut, `autopilot: build a REST API for managing tasks`.

## The prebuild-install deprecation comes from better-sqlite3, not from the package

The global install prints a line you will probably search for later:

```text
deprecated prebuild-install@7.1.3
```

The project traces it to a specific dependency chain rather than leaving it ambiguous. The warning does not originate in oh-my-claude-sisyphus itself but in an upstream native addon, where better-sqlite3 pulls in prebuild-install, and prebuild-install@7.1.3 is still the newest published version of that package. Because the upstream has not moved, the project states there is no safe repository side dependency bump or override that would silence it, and the warning is tracked as issue 2913. The stated meaning is narrow but useful: this line on its own does not mean the OMC CLI install failed. Confirm a good install by running the setup command and seeing the command resolve, not by reading npm's log for warning free output.

## --plugin-dir-mode exists so the installer does not write skills twice

If you start the runtime by pointing it at a plugin directory, the installer has to be told, or you end up with the same assets in two places. When you run `omc --plugin-dir <path>` or `claude --plugin-dir <path>`, you are expected to add `--plugin-dir-mode` to `omc setup`, or export `OMC_PLUGIN_ROOT` before running it, so the installer skips writing skills and agents that the plugin already provides at runtime. The README sends you to a plugin directory flags section in REFERENCE.md for the complete decision matrix and every available flag. Getting this wrong does not throw anything. The described effect is duplication, and nothing in the instructions describes a later reconciliation pass that would collapse the two copies, so the mismatch is something you have to notice and clean up yourself.

## Four stage sequences are admitted, and environment variables cannot define profiles

A named profile is selected only through the flag, never inferred from the task text:

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

Profiles are configuration, defined under `autopilot.workflows` in .claude/omc.jsonc for a project or in ~/.config/claude-omc/config.jsonc for a user, and a v1 profile holds exactly two things, `version: 1` and a `stages` array, with no other keys admitted. The vocabulary of stage names is closed. The admitted sequences are [ralplan, execution], [ralplan, execution, ralph], [ralplan, execution, qa], and [ralplan, execution, ralph, qa], and nothing else qualifies as a profile. Precedence is absolute rather than merged, since a project profile of the same name wholly replaces the user profile while differently named profiles coexist. Environment variables cannot define profiles, and invocations without --workflow stay compatible with the legacy behaviour.

## Named profiles are refused on any host without Linux flock

The platform requirement is narrow and the refusal is deliberate. Named profiles currently require Linux with the `flock` utility, for two concrete reasons: the transcript evidence boundary relies on Linux no-follow file descriptor traversal, and the recoverable mutation lock relies on kernel advisory locking. On an unsupported environment an explicit --workflow invocation is rejected before any autopilot state is created or changed, which means you find out early rather than after a half configured run. Legacy autopilot remains available there, so the failure is a refused flag rather than a broken session, and the rejection happens before any state is written rather than midway through a stage run. The consequence for a team is that one config file and one command produce different outcomes on a Linux box and on a Mac, and the documentation names no alternative lock implementation for the other platforms.

## v1 excludes stageModels, inline execution, arbitrary stages, and plugins

The scope of the feature is written as a list of exclusions, and it is a short one. There are no model fields and no routing, so a `stageModels` key in a profile is not part of the contract. There is no inline execution, no dynamic commands, modes, or state, no arbitrary stages, and no plugins. The custom skill frontmatter parser mismatch is called out as its own separate item rather than folded into the rest. The boundary is recorded in an architecture decision record at docs/adr/03487-named-autopilot-stage-profiles.md with a matching reference section. For someone designing a pipeline, the cost is that stage names are a fixed vocabulary, so a workflow needing a different shape must be bent into one of the four admitted sequences rather than written as the stages you actually want to run.

## One build command assembles generated prompts, bridges, and servers

The repository ships one entry point and three binaries, and the build is correspondingly long. The build script runs build:contained-fs, verifies skill entitlements through generate-skill-entitlements.mjs --verify, then runs tsc, then generates workflow stage prompts, the skill bridge, the MCP server, the bridge entry, composed docs, prompt projections, the Claude md coordinator, the runtime CLI, the team server, and finally the CLI. Skills, hooks, and the MCP surface are generated rather than hand maintained, which is why a build can type check cleanly and still ship a missing prompt. The published file list makes the shipping surface explicit, covering dist, agents, bin, bridge, commands, hooks, scripts, skills, templates, docs, .claude-plugin, .mcp.json, and native, so anything outside that set is not part of the distributed package.

## Conclusion

This project suits teams already working inside Claude Code who want repeatable, named stage sequences rather than ad hoc prompts, and who run on Linux so the workflow machinery is available at all. It does not suit a macOS or Windows user hoping for the same named profiles, a solo developer who finds the extra layer overkill, or anyone who wants model routing per stage, because v1 excludes that outright. Before adopting it, confirm you know which of the two surfaces you are using, the terminal CLI or the in-session skills, check that the plugin is installed through the marketplace so you do not also have a global npm copy writing the same skills, and decide on one host where the Linux flock requirement is satisfied before you standardize a config file.

## FAQ

### How do I install oh my claude code?

Run `/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode` and then `/plugin install oh-my-claudecode` as two separate Claude Code slash commands, entering them one at a time because pasting both together fails. The alternative is the global npm package, `npm i -g oh-my-claude-sisyphus@latest`, followed by `omc setup`.

### what is oh my claude code

It is a multi-agent orchestration layer for Claude Code that exposes two separate surfaces, terminal CLI commands run as `omc ...` and in-session skills run as `/...` inside a Claude Code session. The npm package is published under the name oh-my-claude-sisyphus even though the repository is oh-my-claudecode.

### how to use oh my claude code

After installation, run `/omc-setup` in a session or `omc setup` in a terminal, then hand work to `/autopilot "build a REST API for managing tasks"` or the `autopilot:` shortcut. Named stage sequences are added with `/autopilot --workflow <name> <task>` once a profile exists in config.

### oh-my-codex vs oh-my-claude code

They target different CLIs. The project points Codex users to oh-my-codex, which it describes as the same orchestration experience for the OpenAI Codex CLI, while oh-my-claudecode itself orchestrates agents inside Claude Code.

### oh-my-claude code alternative

The project names two of its own. For Codex CLI users it points to oh-my-codex, and for people who find this layer a bit overkill it points to gajae-code, which keeps Claude OAuth as is and adds an SDK based integration path for runtimes such as OpenClaw, Hermes, and Grokbot.

## Sources

- [Official documentation](https://oh-my-claudecode.dev)
- [Official README](https://github.com/Yeachan-Heo/oh-my-claudecode#readme)
- [Project repository](https://github.com/Yeachan-Heo/oh-my-claudecode)
- [Release notes](https://github.com/Yeachan-Heo/oh-my-claudecode/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yeachan-heo-oh-my-claudecode