oh-my-claude-sisyphus

oh-my-claudecode

     

For Codex users: Check out oh-my-codex — the same orchestration experience for OpenAI Codex CLI.

Multi-agent orchestration for Claude Code. Zero learning curve.

_Don't learn Claude Code. Just use OMC._

Get Started • Documentation • CLI Reference • Workflows • Migration Guide • Discord

Core Maintainers

Ambassadors

Document Specialists

Top Collaborators

Quick Start

Step 1: Install

Marketplace/plugin install (recommended for most Claude Code users). These are Claude Code slash commands — enter them one at a time (pasting both lines at once will fail):

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

Then:

/plugin install oh-my-claudecode

If you prefer the npm CLI/runtime path instead of the marketplace flow:

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

Known npm warning: npm may print deprecated [email protected] during the CLI install.

This currently comes from the upstream better-sqlite3 native-addon dependency

(better-sqlite3 -> prebuild-install); [email protected] is still the latest

published version, so there is no safe repo-side dependency bump or override to remove

the warning yet. The warning is tracked in #2913

and does not by itself mean the OMC CLI install failed.

Step 2: Setup

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

# From your terminal
omc setup

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 doesn't duplicate skills/agents that the plugin already provides at runtime. See the Plugin directory flags section in REFERENCE.md for a complete decision matrix and all available flags.

Step 3: Build something

# 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

That's it. Everything else is automatic.

CLI Commands vs In-Session Skills

OMC exposes two different surfaces:

• •Terminal CLI commands: run omc ... from your shell after installing the npm/runtime path (npm i -g oh-my-claude-sisyphus@latest) or from a local checkout.
• •In-session skills: run /... inside a Claude Code session after installing the plugin/setup flow.

Not Sure Where to Start?

If you're uncertain about requirements, have a vague idea, or want to micromanage the design:

/deep-interview "I want to build a task management app"

The deep interview uses Socratic questioning to clarify your thinking before any code is written. It exposes hidden assumptions and measures clarity across weighted dimensions, ensuring you know exactly what to build before execution begins.

Team Mode (Recommended)

Starting in v4.1.7, Team is the canonical orchestration surface in OMC. The legacy swarm keyword/skill has been removed; use team directly.

/team 3:executor "fix all TypeScript errors"

Use /team ... when you want Claude Code's in-session native team workflow. Use omc team ... when you want terminal-launched tmux CLI workers (claude / codex / gemini panes).

Team runs as a staged pipeline:

team-plan → team-prd → team-exec → team-verify → team-fix (loop)

Enable Claude Code native teams in ~/.claude/settings.json:

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

If teams are disabled, OMC will warn you and fall back to non-team execution where possible.

tmux CLI Workers — Codex & Gemini (v4.4.0+)

v4.4.0 removes the Codex/Gemini MCP servers (x, g providers). Use the CLI-first Team runtime (omc team ...) to spawn real tmux worker panes:

omc team 2:codex "review auth module for security issues"
omc team 2:gemini "redesign UI components for accessibility"
omc team 1:claude "implement the payment flow"
omc team status auth-review
omc team shutdown auth-review

/omc-teams remains as a legacy compatibility skill and now routes to omc team ....

For mixed Codex + Gemini work in one command, use the `/ccg` skill (routes via /ask codex + /ask gemini, then Claude synthesizes):

/ccg Review this PR — architecture (Codex) and UI components (Gemini)

Workers spawn on-demand and die when their task completes — no idle resource usage. Requires codex / gemini CLIs installed and an active tmux session.

Native team worker worktrees are being added behind an opt-in/config gate. See Native Team Worktree Mode for the workspace contract, canonical state-root rules, dirty-worktree preservation policy, and verification checklist.

Note: Package naming — The project is branded as oh-my-claudecode (repo, plugin, commands), but the npm package is published as `oh-my-claude-sisyphus`. If you install or upgrade the CLI tools via npm/bun, use npm i -g oh-my-claude-sisyphus@latest; the package installs both oh-my-claudecode and the short omc command aliases.

Updating

If you installed OMC via npm, upgrade with the published package name:

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

Package naming note: the repo, plugin, and commands are branded oh-my-claudecode, but the published npm package name remains oh-my-claude-sisyphus. npm installs expose both oh-my-claudecode and omc; examples prefer omc for brevity.

If you installed OMC via the Claude Code marketplace/plugin flow, update with:

# 1. Update the marketplace clone
/plugin marketplace update omc

# 2. Re-run setup to refresh configuration
/setup

If you are developing from a local checkout or git worktree, update the checkout first, then re-run setup from that worktree so the active runtime matches the code you are testing.

Note: If marketplace auto-update is not enabled, you must manually run /plugin marketplace update omc to sync the latest version before running setup.

If you experience issues after updating, clear the old plugin cache:

/omc-doctor

<h1 align="center">Your Claude Just Have been Steroided.</h1>

<p align="center"> <img src="assets/omc-character.jpg" alt="oh-my-claudecode" width="400" /> </p>

Why oh-my-claudecode?

• •Zero configuration required - Works out of the box with intelligent defaults
• •Team-first orchestration - Team is the canonical multi-agent surface
• •Natural language interface - No commands to memorize, just describe what you want
• •Automatic parallelization - Complex tasks distributed across specialized agents
• •Persistent execution - Won't give up until the job is verified complete
• •Cost optimization - Smart model routing saves 30-50% on tokens
• •Learn from experience - Automatically extracts and reuses problem-solving patterns
• •Real-time visibility - HUD statusline shows what's happening under the hood

Features

Orchestration Modes

Multiple strategies for different use cases — from Team-backed orchestration to token-efficient refactoring. Learn more →

Goal Workflow Guidance

Use only one primary loop authority in a session. Claude Code /goal is useful for a native cross-turn completion condition, while Ralph owns single-agent verified completion, Team owns parallel staged execution, and UltraQA owns repeated quality-gate cycling. Artifact-only Ultragoal is the safe fallback when you need durable goal artifacts and evidence without starting another loop.

For /goal behavior, rely on Claude Code/Anthropic sources: the Claude Code `/goal` docs and Anthropic Claude Code changelog. Do not claim the /goal evaluator independently runs commands or reads files; surface test output, diffs, and review evidence in the conversation before treating a goal as proven.

Intelligent Orchestration

• •19 specialized agents (with tier variants) for architecture, research, design, testing, data science
• •Smart model routing - Haiku for simple tasks, Opus for complex reasoning
• •Automatic delegation - Right agent for the job, every time
• •[Model × Agent Compatibility Matrix](docs/agents/model-compatibility.md) - Which model to pair with each agent, with premium/balanced/budget presets

Developer Experience

• •Magic keywords - ralph, ulw, ralplan; Team stays explicit via /team
• •HUD statusline - Real-time orchestration metrics in your status bar

- If you launch Claude Code directly with claude --plugin-dir <path> (bypassing the omc shim), export OMC_PLUGIN_ROOT=<path> in your shell so the HUD bundle resolves to the same checkout as the plugin loader. See the Plugin directory flags section in REFERENCE.md for details.

• •Skill learning - Extract reusable patterns from your sessions
• •Analytics & cost tracking - Understand token usage across all sessions

Contributing

Want to contribute to OMC? See CONTRIBUTING.md for the full developer guide, including how to fork, set up a local checkout, link it as your active plugin, run tests, and submit PRs.

Custom Skills

Learn once, reuse forever. OMC extracts hard-won debugging knowledge into portable skill files that auto-inject when relevant.

# .omc/skills/fix-proxy-crash.md
---
name: Fix Proxy Crash
description: aiohttp proxy crashes on ClientDisconnectedError
triggers: ["proxy", "aiohttp", "disconnected"]
source: extracted
---
Wrap handler at server.py:42 in try/except ClientDisconnectedError...

Skillify: /skillify extracts reusable patterns with strict quality gates Auto-inject: Matching skills load into context automatically — no manual recall needed

Project-scoped OMC-authored skills are stored in .omc/skills/ and are intended to be committed when you want them shared. During slash/skill execution OMC also reads Claude Code workspace skills from .claude/skills/ and compatibility skills from .agents/skills/, so existing workspace-local SKILL.md packages remain callable without copying them into user-global skills. If you create project-local skills inside a linked git worktree and do not commit them, they disappear when that worktree is removed.

Full feature list →

Multi-repo workspaces

When several independent git repos share a parent directory, drop a .omc-workspace marker at the parent so all sub-repos share one .omc/ state root:

cd /path/to/parent-dir-with-many-repos
echo '{"id":"my-workspace"}' > .omc-workspace
# Sessions inside any sub-repo now share /path/.omc/
# For parallel ultragoal runs:
cd repo-A && omc ultragoal create-goals --auto-plan-id --brief "..."
cd ../repo-B && omc ultragoal create-goals --auto-plan-id --brief "..."

See Multi-repo workspaces in REFERENCE.md for resolution order, OMC_STATE_DIR, and workspace identifier options.

In-session shortcuts

These shortcuts run inside a Claude Code / OMC session, not as terminal CLI commands. For shell commands, use the omc ... forms shown above. Team mode is explicit: use /team ... in-session or omc team ... from your shell rather than expecting a bare team keyword trigger.

Notes:

• •ralph includes ultrawork: when you activate ralph mode, it automatically includes ultrawork's parallel execution.
• •swarm compatibility alias has been removed; migrate existing prompts to /team syntax.
• •plan this / plan the keyword triggers were removed; use ralplan or explicit /oh-my-claudecode:plan.

Utilities

Provider Advisor (omc ask / /ask)

Run local provider CLIs and save a markdown artifact under .omc/artifacts/ask/.

# Terminal CLI
omc ask claude "review this migration plan"
omc ask codex --prompt "identify architecture risks"
omc ask gemini --prompt "propose UI polish ideas"
omc ask grok --prompt "cross-check this code review"
omc ask cursor --prompt "apply this implementation plan"
omc ask claude --agent-prompt executor --prompt "draft implementation steps"

# Inside a Claude Code / OMC session
/ask claude "review this migration plan"
/ask codex "identify architecture risks"
/ask cursor "apply this implementation plan"

Canonical env vars:

• •OMC_ASK_ADVISOR_SCRIPT
• •OMC_ASK_ORIGINAL_TASK

Phase-1 aliases OMX_ASK_ADVISOR_SCRIPT and OMX_ASK_ORIGINAL_TASK are accepted with deprecation warnings.

Autoresearch (stateful skill)

omc autoresearch is now a hard-deprecated shim. The authoritative workflow is:

/deep-interview --autoresearch improve startup performance
/oh-my-claudecode:autoresearch

• •deep-interview --autoresearch generates/sets up the mission and evaluator
• •autoresearch runs the bounded, single-mission stateful loop
• •each iteration records evaluation JSON plus markdown decision logs
• •non-passing iterations continue
• •strict stopping is controlled by an explicit max-runtime ceiling

Rate Limit Wait

Auto-resume Claude Code sessions when rate limits reset.

omc wait          # Check status, get guidance
omc wait --start  # Enable auto-resume daemon
omc wait --stop   # Disable daemon

Requires: tmux (for session detection)

Monitoring & Observability

Use the HUD for live observability and the current session/replay artifacts for post-session inspection:

• •HUD preset: /oh-my-claudecode:hud setup then use a supported preset such as "omcHud": { "preset": "focused" }
• •Session summaries: .omc/sessions/*.json
• •Replay logs: .omc/state/agent-replay-*.jsonl
• •Live HUD rendering: omc hud

Notification Tags (Telegram/Discord/Slack)

You can configure who gets tagged when stop callbacks send session summaries.

# Set/replace tag list
omc config-stop-callback telegram --enable --token <bot_token> --chat <chat_id> --tag-list "@alice,bob"
omc config-stop-callback discord --enable --webhook <url> --tag-list "@here,123456789012345678,role:987654321098765432"
omc config-stop-callback slack --enable --webhook <url> --tag-list "<!here>,<@U1234567890>"

# Incremental updates
omc config-stop-callback telegram --add-tag charlie
omc config-stop-callback discord --remove-tag @here
omc config-stop-callback discord --clear-tags

Tag behavior:

• •Telegram: alice becomes @alice
• •Discord: supports @here, @everyone, numeric user IDs, and role:<id>
• •Slack: supports <@MEMBER_ID>, <!channel>, <!here>, <!everyone>, <!subteam^GROUP_ID>
• •file callbacks ignore tag options

OpenClaw Integration

Forward Claude Code session events to an OpenClaw gateway to enable automated responses and workflows via your OpenClaw agent.

Quick setup (recommended):

/oh-my-claudecode:configure-notifications
# → When prompted, type "openclaw" → choose "OpenClaw Gateway"

Manual setup: create ~/.claude/omc_config.openclaw.json:

{
  "enabled": true,
  "gateways": {
    "my-gateway": {
      "url": "https://your-gateway.example.com/wake",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" },
      "method": "POST",
      "timeout": 10000
    }
  },
  "hooks": {
    "session-start": {
      "gateway": "my-gateway",
      "instruction": "Session started for {{projectName}}",
      "enabled": true
    },
    "stop": {
      "gateway": "my-gateway",
      "instruction": "Session stopping for {{projectName}}",
      "enabled": true
    }
  }
}

Environment variables:

Supported hook events (6 active in bridge.ts):

Reply channel environment variables:

See scripts/openclaw-gateway-demo.mjs for a reference gateway that relays OpenClaw payloads to Discord via ClawdBot.

Documentation

• •[Full Reference](docs/REFERENCE.md) - Complete feature documentation
• •[CLI Reference](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#cli-reference) - All omc commands, flags, and tools
• •[Notifications Guide](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#notifications) - Discord, Telegram, Slack, and webhook setup
• •[Recommended Workflows](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#workflows) - Battle-tested skill chains for common tasks
• •[Release Notes](https://yeachan-heo.github.io/oh-my-claudecode-website/docs/#release-notes) - What's new in each version
• •[Website](https://yeachan-heo.github.io/oh-my-claudecode-website) - Interactive guides and examples
• •[Migration Guide](docs/MIGRATION.md) - Upgrade from v2.x
• •[Architecture](docs/ARCHITECTURE.md) - How it works under the hood
• •[Performance Monitoring](docs/PERFORMANCE-MONITORING.md) - Agent tracking, debugging, and optimization
• •[Model × Agent Compatibility Matrix](docs/agents/model-compatibility.md) - Which model to pair with each agent (premium / balanced / budget presets)
• •[Security Guide](SECURITY.md) - Enterprise deployment and hardening

Requirements

• •Claude Code CLI
• •Claude Max/Pro subscription OR Anthropic API key

Platform & tmux

OMC features like omc team and rate-limit detection require tmux:

Windows users: psmux provides a native tmux binary for Windows with 76 tmux-compatible commands. No WSL required.

Optional: Multi-AI Orchestration

OMC can optionally orchestrate external AI providers for cross-validation and design consistency. These are not required — OMC works fully without them.

Cost: 3 Pro plans (Claude + Gemini + ChatGPT) cover everything for ~$60/month.

License

MIT

<div align="center">

Inspired by: oh-my-opencode • claude-hud • Superpowers • everything-claude-code • Ouroboros

Zero learning curve. Maximum power.

</div>

<!-- OMC:FEATURED-CONTRIBUTORS:START -->

Featured by OmC Contributors

Top personal non-fork, non-archived repos from all-time OMC contributors (100+ GitHub stars).

• •@Yeachan-Heo — oh-my-claudecode (⭐ 36k)
• •@junhoyeo — tokscale (⭐ 3.6k)
• •@psmux — psmux (⭐ 2.4k)
• •@BowTiedSwan — buildflow (⭐ 292)
• •@J-Pster — Psters_AI_Workflow (⭐ 290)
• •@alohays — awesome-visual-representation-learning-with-transformers (⭐ 267)
• •@jcwleo — random-network-distillation-pytorch (⭐ 262)
• •@MeroZemory — ida-multi-mcp (⭐ 261)
• •@shaun0927 — openchrome (⭐ 216)
• •@HaD0Yun — Doyunha-Gopeak (⭐ 205)
• •@emgeee — mean-tutorial (⭐ 200)
• •@anduinnn — HiFiNi-Auto-CheckIn (⭐ 171)
• •@devswha — patina (⭐ 156)
• •@Znuff — consolas-powerline (⭐ 146)

<!-- OMC:FEATURED-CONTRIBUTORS:END -->

Star History


💖 Support This Project

If Oh-My-ClaudeCode helps your workflow, consider sponsoring:


Why sponsor?

• •Keep development active
• •Priority support for sponsors
• •Influence roadmap & features
• •Help maintain free & open source

Other ways to help

• •⭐ Star the repo
• •🐛 Report bugs
• •💡 Suggest features
• •📝 Contribute code

GEO visibility benchmark

OmC includes a `geobench` product spec for measuring LLM hit rate, MRR, share of voice, and citations.

• •Spec: `geobench/oh-my-claudecode.yaml`
• •Runbook: `docs/geobench.md`