Oh My Claudecode Documentation

Transform Claude Code into an intelligent multi-agent orchestration system. You become the conductor, not the performer.

#Release Notes

#Installation

# 1. Add the plugin
/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode

# 2. Install it
/plugin install oh-my-claudecode

# 3. Run setup wizard
/oh-my-claudecode:omc-setup

#Quick Start

OMC uses "Magic Keywords" to detect your intent. Just describe what you want to do.

• Uncertain About Requirements?

  "/deep-interview 'I want to build a task manager'" — Socratic questioning to clarify vague ideas before execution.

• Autonomous Building

  "autopilot build a React dashboard" — Full autonomous execution from idea to code.

• Refactoring

  "ralph refactor the API" — Persists until verified clean ("The boulder never stops").

• Parallel Work

  "ulw fix all typescript errors" — Runs multiple agents in parallel for speed.

• Native Teams

  "team 5:executor refactor backend" — Spawns a team of 5 agents coordinated by a lead.

• Planning

  "plan the auth system" — Starts an interactive planning interview.

#Conductor Philosophy

The core principle of OMC is: You are the conductor, not the performer.

Agents have specialized roles. The architect sees the big picture, the executor writes the code, and the verifier proves it works. Respecting this division ensures higher quality output.

#Team Architecture

v4.1 leverages a native staged pipeline for teams. Transitions are strictly defined to ensure quality gates.

#Model Routing

OMC intelligently routes tasks to the most appropriate model tier to balance cost and capability.

#Delegation Rules

• ✅ Delegate: Multi-file implementations, refactors, debugging, reviews, planning, research, verification.
• 🛑 Do It Yourself: Small clarifications, quick status checks, single-command operations. Direct writes are OK for .omc/, .claude/ config files.

#Execution Modes

#Team Compositions

#Agent Catalog

OMC provides a unified catalog of 19 specialized agents across 3 functional lanes. Each agent is optimized for specific tasks using the most appropriate model tier.

#MCP Tools

External AI

• Codex (gpt-5.3-codex): Architectural reasoning, deep review, security analysis.
• Gemini (gemini-3-pro-preview): Visual analysis, UI design, 1M token context.

Code Intelligence

LSP Tools: lsp_hover, lsp_goto_definition, lsp_find_references, lsp_diagnostics, lsp_rename.

AST Grep: ast_grep_search, ast_grep_replace for structural refactoring.

Team & Task Coordination

Team API: TeamCreate, TaskCreate, TaskList, TaskGet, TaskUpdate, SendMessage.

Workflows: omc ask <claude|codex|gemini> for tri-model orchestration.

Python REPL: Persistent environment for data analysis.

#Team API Reference

The Team API provides granular control over multi-agent orchestration. It allows you to programmatically manage teams, tasks, and inter-agent communication.

Example: Programmatic Delegation

// 1. Create a specialized team
TeamCreate(team_name="ui-redesign", workers=["designer", "executor", "verifier"]);

// 2. Assign tasks
TaskCreate(
  team_name="ui-redesign",
  subject="Hero Section",
  description="Redesign the hero section with a focus on modern visual effects."
);

// 3. Monitor progress
const tasks = TaskList(team_name="ui-redesign", status_filter="completed");

#Skills & Commands

Utility Skills: /oh-my-claudecode:cancel, note, omc-setup, hud, doctor.

#State & Memory

Notepad System

Located at .omc/notepad.md. Resilient memory surviving context pruning.

• Priority: Always injected into context.
• Working: Auto-pruned after 7 days.
• Manual: Never pruned.

Project Memory

Located at .omc/project-memory.json. Stores tech stack, conventions, and architectural directives.

#Configuration

Run /oh-my-claudecode:omc-setup to configure defaults.

Worktree Paths:

• .omc/state/ - Mode state files
• .omc/logs/ - Audit logs
• .omc/plans/ - Planning documents

#CLI Reference

The omc command-line tool lets you launch, configure, and manage OMC from your terminal.

#Getting Started

Install OMC globally, then run it.

npm install -g oh-my-claude-sisyphus
omc

Three aliases all run the same CLI: omc, oh-my-claudecode, omc-cli.

#Core Commands

#Launch Flags

#Teleport

Teleport helps you create and manage git worktrees quickly.

# Create worktree from issue/PR number
omc teleport '#42'

# Create worktree for a feature branch
omc teleport add-auth

# List all worktrees
omc teleport list

# Remove a worktree
omc teleport remove ./path

# From a full URL
omc teleport https://github.com/owner/repo/issues/42

Supports GitHub, GitLab, Bitbucket, and Azure DevOps.

#Wait

The wait command helps you monitor rate limits and auto-resume blocked sessions.

# Check rate limit status
omc wait

# Start auto-resume daemon
omc wait --start

# Control background daemon
omc wait daemon start
omc wait daemon stop

# Scan for blocked sessions
omc wait detect

# Show detailed status
omc wait status

#Notification Profiles

Set up notification channels from the command line, then use named profiles to switch between them.

# Set up channels
omc config-stop-callback telegram --enable --token <token> --chat <id>
omc config-stop-callback discord --enable --webhook <url>
omc config-stop-callback slack --enable --webhook <url>
omc config-stop-callback file --enable --path ~/.claude/logs/{date}.md

# Manage profiles
omc config-notify-profile --list
omc config-notify-profile work --show

# Launch with a profile
OMC_NOTIFY_PROFILE=work omc

#Other Commands

# Split-pane tmux with Claude + Codex side by side
omc interop

# Run the HUD status line
omc hud

# Live HUD refresh every second
omc hud --watch --interval 1000

omc interop opens a split-pane tmux layout with Claude and Codex side by side. Requires both CLIs installed.

omc hud shows a status line with session info. Use --watch for live updates.

#Notifications

#Overview

Notifications tell you when Claude finishes work, needs your input, or hits a problem.

It works with Discord, Telegram, Slack, and any webhook endpoint.

Notifications are non-blocking, so they never slow down your work.

Each platform stays dormant until you activate it with a CLI flag in that session.

#Quick Setup

The easiest setup is running /oh-my-claudecode:configure-notifications inside Claude Code.

It walks you through each step with prompts.

You can also configure everything manually using the sections below.

#Supported Platforms

Telegram

• Create a bot with @BotFather on Telegram and copy the bot token.
• Send your bot a message, then get your chat ID.
• Add notifications.telegram.botToken and notifications.telegram.chatId to config.
• Activate per session with omc --telegram.

Discord (Webhook)

• In your channel: Settings > Integrations > Webhooks > New Webhook.
• Copy the webhook URL.
• Add notifications.discord.webhookUrl to config.
• Optional mentions: <@USER_ID> for a user, <@&ROLE_ID> for a role.
• Activate per session with omc --discord.

Discord (Bot API)

• Create a bot in the Discord Developer Portal and copy the bot token.
• Get the channel ID (right-click channel > Copy ID with developer mode on).
• Add notifications.discordBot.botToken and notifications.discordBot.channelId to config.
• Activate per session with omc --discord.

Slack

• Create an app at api.slack.com and enable Incoming Webhooks.
• Add a webhook to your workspace and copy the URL.
• Add notifications.slack.webhookUrl to config.
• Optional mentions: <@UXXXXXXXX>, <!channel>, <!here>.
• Activate per session with omc --slack.

Generic Webhook

• Use any HTTPS endpoint that accepts JSON POST requests.
• Add notifications.webhook.url to config.
• Optional: add custom headers with notifications.webhook.headers.
• Activate per session with omc --webhook.

#Notification Events

#Verbosity Levels

Set this with notifications.verbosity in config or the OMC_NOTIFY_VERBOSITY environment variable.

#Environment Variables

Use these for zero-config setup without editing files:

• OMC_TELEGRAM_BOT_TOKEN + OMC_TELEGRAM_CHAT_ID — Telegram without config file.
• OMC_DISCORD_WEBHOOK_URL — Discord without config file.
• OMC_SLACK_WEBHOOK_URL — Slack without config file.
• OMC_NOTIFY_VERBOSITY — Set verbosity level.
• OMC_NOTIFY=0 — Turn off all notifications.
• OMC_NOTIFY_PROFILE — Use a named notification profile.

#Custom Message Templates

• Template file: ~/.claude/omc_config.hook.json
• Use {{variable}} placeholders: {{sessionId}}, {{timestamp}}, {{projectName}}, {{reason}}, {{duration}}
• Use conditionals: {{#if variable}}show this{{/if}}
• Computed values: duration, time, modesDisplay, agentDisplay, footer, tmuxTailBlock
• You can set different templates per event and per platform.

#Example Config

{
  "notifications": {
    "verbosity": "session",
    "telegram": {
      "botToken": "123456:ABC-DEF",
      "chatId": "-1001234567890"
    },
    "discord": {
      "webhookUrl": "https://discord.com/api/webhooks/...",
      "mention": "<@123456789>"
    },
    "slack": {
      "webhookUrl": "https://hooks.slack.com/services/T.../B.../xxx"
    },
    "events": {
      "session-end": { "telegram": true, "discord": true },
      "ask-user-question": { "telegram": true },
      "session-start": { "discord": true }
    }
  }
}

Put this in ~/.claude/.omc-config.json.

#Reply Injection

This is an advanced feature for answering Claude from your phone.

• A background daemon polls Discord or Telegram for your replies.
• When you reply to a notification, your text is sent back to your tmux pane.
• This lets you answer Claude's questions remotely.
• Configure replyListener in .omc-config.json with polling interval and authorized user IDs.
• Security: rate limiting, input sanitization, and pane verification before injection.

#Recommended Workflows

These are battle-tested workflows for common tasks. Each one chains OMC skills together in a proven order. Pick the one that fits your situation.

#Full-Auto from PRD

#No-Brainer

#Fix / Debugging

#Parallel Issue / Ticket Handling

#Getting Started

This guide walks you through installing OMC, running the setup wizard, and executing your first command.

Installation

Install OMC with a single command:

curl -fsSL https://raw.githubusercontent.com/yeachan-heo/oh-my-claudecode/main/install.sh | bash

First Setup

Once installed, open Claude Code and run the setup wizard. This configures hooks, agents, skills, and MCP tools.

/omc-setup

Your First Command

Try a simple autopilot command to see OMC in action. Autopilot detects your intent, plans the work, executes it, and verifies the result.

autopilot build a hello world REST API

Verify Your Installation

Run the diagnostic tool to confirm everything is set up correctly. It checks hooks, MCP tools, agent availability, and configuration.

/omc-doctor

#Execution Modes Guide

OMC provides several execution modes, each optimized for different types of work. Choose the mode that best fits your task.

Autopilot

Full autonomous execution. Autopilot detects your intent, expands requirements with an Analyst and Architect, plans the work, executes with Ralph and Ultrawork, and verifies the result with UltraQA. This is the flagship mode for greenfield features and "build me X" requests.

autopilot build a user auth system with JWT

When to use: Greenfield features, new projects, "build me X" requests where you want end-to-end autonomous execution.

Ralph

Self-referential persistence loop. Ralph keeps working until the task is verified complete by the Architect. It automatically includes Ultrawork for parallelism. The motto is "The boulder never stops" -- Ralph will iterate, fix failures, and re-verify until the goal is met.

ralph refactor the entire API layer

When to use: Complex multi-step tasks that need iteration, refactors that touch many files, tasks where you want guaranteed completion.

Ultrawork

Maximum parallelism. Ultrawork aggressively delegates subtasks to multiple background agents running concurrently (up to 5+ agents). It uses smart model routing to assign the right model tier to each subtask.

ulw fix all 5 failing tests

When to use: Batch operations, multiple independent fixes, any work that can be split into parallel subtasks.

Team

N coordinated Claude agents with a shared task list. Team mode follows a stage-aware pipeline: plan, PRD, exec, verify, fix. Each stage routes to the appropriate specialist agents. Teams support composition with Ralph for persistent execution (team ralph).

team 3:executor build the dashboard

When to use: Large features requiring multiple specialists, projects that benefit from coordinated parallel agents with quality gates.

Plan

Strategic planning with optional interview workflow. Plan mode analyzes your request and produces a structured execution plan. Use --consensus for iterative planning with Planner, Architect, and Critic until they agree. Use --deliberate for high-risk work with pre-mortem analysis.

plan the database migration strategy

When to use: Architecture decisions, migration planning, any task where upfront planning reduces rework.

UltraQA

QA cycling -- test, verify, fix, repeat. UltraQA runs end-to-end tests, verifies results, fixes failures, and repeats until all tests pass. It is typically activated by Autopilot after implementation, but can be triggered independently.

/ultraqa

When to use: Ensuring quality after implementation, running comprehensive test suites, validating that all acceptance criteria are met.

#Model Routing Guide

OMC intelligently routes each agent to the most appropriate model tier. This balances cost, speed, and capability so that simple tasks use fast lightweight models while complex tasks get the full power of Opus.

The Three Tiers

• Haiku -- Fast and cheap. Used for quick lookups, codebase exploration, simple documentation, and formatting tasks.
• Sonnet -- The workhorse. Used for standard implementation, code reviews, test writing, refactoring, and most day-to-day agent work.
• Opus -- Maximum capability. Used for architecture design, deep analysis, complex autonomous work, and critical decision-making.

Agent-to-Model Mapping

Overriding Model Routing

You can override the default model tier for any agent by passing the model parameter on Task calls. This is useful when you want a higher-quality result for a normally-Sonnet agent, or a faster result for a normally-Opus agent.

# Use Opus for an executor task that needs extra reasoning
Task(subagent_type="oh-my-claudecode:executor", model="opus", ...)

# Use Haiku for a quick verification check
Task(subagent_type="oh-my-claudecode:verifier", model="haiku", ...)

#Troubleshooting

Common issues and how to resolve them.

"not inside tmux"

OMC team and worker features require a tmux session. Start one before launching OMC:

tmux new -s dev

"codex/gemini: command not found"

The Codex and Gemini CLI tools must be installed globally for multi-model features to work:

# Install Codex CLI
npm install -g @openai/codex

# Install Gemini CLI
npm install -g @google/gemini-cli

State Conflicts

If modes get stuck or state files become inconsistent, clear them with the cancel command or the state_clear tool:

# Clear all active mode state
/cancel --force

# Or clear a specific mode's state
state_clear

Agent Not Responding

If an agent appears stuck or is not producing output, check the trace timeline for details and restart:

# Check the agent flow trace for issues
/trace

# Cancel and restart the current mode
/cancel

Hook Errors

If hooks are firing incorrectly or causing errors, check the skip list and run diagnostics:

# Check which hooks are being skipped
echo $OMC_SKIP_HOOKS

# Run the full diagnostic check
/omc-doctor