Guide · Open source

How to use oh-my-claudecode: install, setup and first run

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

oh-my-claudecode (OMC) is an open-source add-on for Claude Code, Anthropic's coding assistant. It adds commands that coordinate several AI agents working on a task in parallel, such as planning, building and QA. This guide shows you how to install it, run setup, start your first autopilot build and check whether it fits your situation.

oh-my-claudecodeYeachan-Heo/oh-my-claudecode · ★ 40.5k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Claude Code is installed and, if you use the npm route, that npm is available.
2Add the marketplace. Inside Claude Code, run the marketplace add command on its own line.
3Install the plugin. Run the plugin install command inside Claude Code as a separate step.
4Run setup. Run /omc-setup in a session or omc setup in your terminal.
5Start an autopilot build. Run /autopilot with a short task description in quotes.
6Check the optional profile limits. If you want named stage profiles, confirm you are on Linux with flock before using --workflow.

What you need before you install OMC

OMC is an add-on, so you need Claude Code first. The install path described in the README also uses npm if you choose the npm CLI route.

OMC is aimed at developers who are comfortable with a terminal on Linux or macOS-style systems. Setup involves slash commands, npm and terminal use, so it is not a no-code tool.

Claude Code installed
npm available (for the npm CLI path)
Comfort with a terminal

Install the OMC plugin in Claude Code

The README recommends the marketplace (plugin) install for most Claude Code users. These are Claude Code slash commands, so enter them inside Claude Code one at a time. Pasting both lines together will fail.

If you prefer the npm CLI and runtime path instead, the README gives a separate global install command.

Enter the marketplace command first, then the install command, one at a time.
The npm route is an alternative, not a required extra step.

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

# Alternative npm CLI install
npm i -g oh-my-claude-sisyphus@latest

Run OMC setup

After installing, run setup. You can run it from inside a Claude Code session with the slash command, or from your terminal with the omc command. Both are listed as real entrypoints in the README.

If you launch OMC with a plugin directory flag, the README says to add --plugin-dir-mode to omc setup (or export OMC_PLUGIN_ROOT first) so the installer does not duplicate skills and agents the plugin already provides.

Inside a session: /omc-setup
From a terminal: omc setup

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

# From your terminal
omc setup

Start your first autopilot build

The README's example task is building a feature from a short description. Use the autopilot command inside a session and describe what you want in quotes. There is also a natural-language shortcut written as a plain line.

The README says that after this, everything else is automatic. The detailed behaviour of each workflow is documented on the external OMC documentation site, not in the README excerpt.

Slash command form: /autopilot followed by your task in quotes
Shortcut form: autopilot: followed by your task

# Inside a Claude Code / OMC session
/autopilot "build a REST API for managing tasks"

# Natural-language in-session shortcut
autopilot: build a REST API for managing tasks

Use named autopilot stage profiles (optional, with a Linux limit)

Named stage profiles let you pick a configured sequence of stages with the --workflow flag. Profiles are set under autopilot.workflows in .claude/omc.jsonc for a project, or in ~/.config/claude-omc/config.jsonc for your user account. A project profile with the same name replaces the user profile.

Named profiles currently require Linux with the flock utility. On unsupported environments, an explicit --workflow call is rejected before autopilot state is changed. Legacy autopilot without --workflow still works.

Allowed stage sequences include [ralplan, execution], [ralplan, execution, ralph], [ralplan, execution, qa] and [ralplan, execution, ralph, qa].
Environment variables cannot define profiles.
V1 does not include model routing (stageModels) or arbitrary stages.

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

// .claude/omc.jsonc
{
  "autopilot": {
    "workflows": {
      "plan-build-qa": {
        "version": 1,
        "stages": ["ralplan", "execution", "qa"]
      }
    }
  }
}

Know the difference between terminal commands and in-session skills

OMC has two surfaces. Terminal CLI commands start with omc and run from your shell. In-session skills start with / and run inside a Claude Code session. The README notes that omc team and /team are different runtimes: the terminal version launches tmux CLI workers, while the slash version runs the in-session native team workflow.

Terminal: omc ask, omc team, omc lookout scan
In session: /ask, /team, /omc-setup, /autopilot

omc team 2:codex "review auth flow"
/team 3:executor "fix all TypeScript errors"

What people use it for

Building a feature, such as a REST API for managing tasks, from a short description using autopilot.
Getting a second opinion from another provider with the ask command, for example reviewing a patch.
Running a team of agents on a coding task, such as fixing TypeScript errors, using the team workflow.
Running a pre-flight scan of a task briefing and workspace before an unattended run with omc lookout scan.

Frequently asked questions

Is oh-my-claudecode free to use?

The project is released under the MIT licence, as stated in the repository. The README excerpt does not cover pricing for Claude Code itself, so check Claude Code's own terms for any costs.

Do I need Claude Code to use OMC?

Yes. OMC is an add-on for Claude Code and is not a standalone tool. People who do not use Claude Code are not the intended audience.

How do I install oh-my-claudecode?

Inside Claude Code, run the marketplace add command, then the plugin install command, one at a time. The README also lists an alternative npm CLI install with npm i -g oh-my-claude-sisyphus@latest.

Why does named autopilot not work on my computer?

Named stage profiles currently require Linux with the flock utility. On other environments, an explicit --workflow call is rejected, but legacy autopilot without that flag remains available.

What is the npm deprecation warning about prebuild-install?

The README says npm may print a deprecated prebuild-install@7.1.3 warning during the CLI install. It comes from an upstream better-sqlite3 dependency and does not by itself mean the install failed. The issue is tracked on the project's GitHub.

How does oh-my-claudecode compare with oh-my-codex and gajae-code?

oh-my-codex offers the same orchestration experience for OpenAI Codex CLI, according to the README. gajae-code is described there as a lighter alternative that keeps Claude OAuth as-is. Pick based on which assistant you use and how much structure you want.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OMC suits developers already on Claude Code who want prebuilt multi-agent workflows and are comfortable with npm and a terminal. Skip it if you do not use Claude Code, need a no-code tool, or work on an environment without flock if you want named stage profiles.

Install options & downloads