Oh My Claudecode Documentation

Transform Claude Code into an intelligent multi-agent orchestration system. You become the conductor, not the performer - delegating complex tasks to specialized AI agents.

#What's New in v4.1.0

#Installation

Install Oh My Claudecode globally using npx:

npx oh-my-claudecode@latest init

This command will:

• Install the OMC plugin to your Claude Code configuration
• Set up necessary hooks and state directories
• Configure default execution preferences
• Optionally install the HUD statusline

Requirements

• Claude Code CLI installed and configured
• Node.js 18+ (for MCP server features)
• Git (for version control features)

Verify Installation

Run the doctor command to verify everything is set up correctly:

/oh-my-claudecode:doctor

#Quick Start

Example Prompts

Here are some example prompts that automatically trigger the right mode:

#Conductor Philosophy

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

What You Do vs. What Agents Do

#Execution Modes

OMC provides several execution modes optimized for different scenarios. Each mode has unique characteristics for handling complexity, parallelism, and verification.

#Autopilot

Example Usage

autopilot: Build a REST API for user management with JWT authentication

# Or simply:
Build me a dashboard that shows real-time analytics

#Ralph

#Ultrawork

Model Routing

#Ecomode

#Ultrapilot

#Team

Architecture

The team lifecycle follows a structured pattern:

1. TeamCreate - Team lead creates a named team
2. TaskCreate - Create tasks with descriptions and dependencies
3. Spawn teammates - Each teammate claims and works on tasks
4. Monitor - Team lead coordinates via SendMessage
5. Shutdown - Graceful shutdown_request to all teammates

Example Usage

/oh-my-claudecode:team 5:executor "fix all TypeScript errors"

# Or with mixed agent types:
/oh-my-claudecode:team 3:executor,2:test-engineer "implement and test the auth module"

#Swarm

#Pipeline

#UltraQA

#Agent Overview

OMC includes 28 specialized agents organized into functional lanes. Each agent excels at specific tasks and uses the appropriate model (haiku, sonnet, or opus).

#Agent Lanes

Agents are organized into functional lanes. Each agent has a default model (haiku, sonnet, or opus) optimized for its role:

Build/Analysis Lane

Review Lane

Domain Specialists

Product Lane

Coordination

#Agent Selection Guide

Choose the right agent based on your task. Each agent has a fixed default model, but you can override it with the model parameter when delegating.

#Agent Domains

#Magic Keywords

Magic keywords are shortcuts that trigger specific modes. They can be used anywhere in your prompt.

#Skills Reference

Skills are invoked with the /oh-my-claudecode: prefix.

Execution Skills

• /oh-my-claudecode:autopilot - Full autonomous execution
• /oh-my-claudecode:ralph - Persistence mode
• /oh-my-claudecode:ultrawork - Maximum parallelism
• /oh-my-claudecode:ecomode - Token-efficient mode
• /oh-my-claudecode:ultrapilot - Parallel autopilot
• /oh-my-claudecode:team - Coordinated team of N agents
• /oh-my-claudecode:swarm - Coordinated agents (SQLite-based)
• /oh-my-claudecode:pipeline - Sequential chaining
• /oh-my-claudecode:ultraqa - QA cycling

Planning Skills

• /oh-my-claudecode:plan - Planning interview (supports --consensus and --review flags)
• /oh-my-claudecode:ralplan - Alias for /plan --consensus
• /oh-my-claudecode:review - Alias for /plan --review
• /oh-my-claudecode:analyze - Deep analysis

Utility Skills

• /oh-my-claudecode:cancel - Stop current operation
• /oh-my-claudecode:note - Add to notepad
• /oh-my-claudecode:help - Show all skills (includes learn-about-omc)
• /oh-my-claudecode:doctor - Diagnose issues
• /oh-my-claudecode:hud - HUD statusline
• /oh-my-claudecode:skill - Manage skills (includes local-skills-setup)

#Cancel Operations

Use the unified /oh-my-claudecode:cancel skill to stop any execution mode.

The cancel skill automatically detects and cancels:

• autopilot, ultrapilot
• ralph, ultrawork, ultraqa
• team, swarm, pipeline
• Planning interviews

If /cancel doesn't work, use:

/oh-my-claudecode:cancel --force

#OMC Setup

Run the setup wizard to configure OMC:

/oh-my-claudecode:omc-setup

The wizard configures:

• Default execution mode preference
• HUD statusline installation
• MCP server configuration
• Task tool selection (built-in, beads, or beads-rust)

#Default Execution Mode

Configure which mode activates when you say "fast" or "parallel" without specifying a mode.

The configuration file is at ~/.claude/.omc-config.json:

{
  "defaultExecutionMode": "ultrawork"  // or "ecomode"
}

Priority Resolution

#HUD Configuration

The HUD (Heads-Up Display) shows real-time status in your terminal.

/oh-my-claudecode:hud setup

HUD shows:

• Current active mode
• Agent status and count
• Task progress
• Token usage

#MCP Server Setup

OMC includes MCP (Model Context Protocol) servers for advanced features.

/oh-my-claudecode:mcp-setup

Available MCP tools:

• LSP tools (hover, definition, references, diagnostics)
• AST grep (search, replace) for structural patterns
• Python REPL for data analysis
• State management tools
• Notepad and project memory tools

#Hooks System

Hooks are OMC extensions that inject context into conversations via <system-reminder> tags.

Hook Events

#Notepad System

The notepad at .omc/notepad.md provides compaction-resilient memory with three tiers.

Usage

/oh-my-claudecode:note <content>              # Working Memory
/oh-my-claudecode:note --priority <content>   # Priority Context
/oh-my-claudecode:note --manual <content>     # MANUAL (never pruned)
/oh-my-claudecode:note --show                 # Display notepad
/oh-my-claudecode:note --prune                # Remove old entries

#State Management

All mutable OMC state belongs under .omc/state/ in the worktree.

.omc/
  state/
    autopilot-state.json
    ralph-state.json
    ultrawork-state.json
    swarm.db           # SQLite for swarm
  notepad.md
  logs/
    delegation-audit.jsonl

State files control hook behavior. The /cancel skill removes these files to allow graceful termination.

#MCP Tools Overview

OMC v4.1.0 includes powerful MCP (Model Context Protocol) tools that extend Claude's capabilities with external AI consultation, language server integration, and more.

#External AI Consultation (Gemini & Codex)

OMC can optionally consult external AI models for specialized tasks:

Agent Roles

Codex roles: architect, planner, critic, analyst, code-reviewer, security-reviewer, tdd-guide

Gemini roles: designer, writer, vision

MCP-Direct Replacement Pattern

Instead of spawning Claude agents for analysis tasks, call MCPs directly:

#LSP Tools

Language Server Protocol integration provides IDE-like features:

#AST Grep

Structural code search and replace using AST patterns - more precise than text search.

Pattern Syntax

• $NAME - matches any single AST node
• $$$ARGS - matches multiple nodes (for arguments, list items)

Example Patterns

# Find all function declarations
function $NAME($$$ARGS)

# Find all console.log calls
console.log($MSG)

# Find null equality checks
$X === null

# Find imports from a specific module
import $$$IMPORTS from '$MODULE'

#Python REPL

Persistent Python environment for data analysis and scientific computing.

Features

• Variables persist between calls within a session
• Pre-installed: pandas, numpy, matplotlib
• Actions: execute, interrupt, reset, get_state

# First call
import pandas as pd
df = pd.read_csv('data.csv')

# Second call (df is still available)
df.describe()

#Background Job Management

External AI consultations can run in the background for better parallelism.

Background Orchestration Pattern

1. SPAWN - Launch with background: true
2. CHECK - Non-blocking status with check_job_status
3. AWAIT - Block when needed with wait_for_job

#Verification Tiers

Verification scales with task complexity:

#Context Persistence

Use <remember> tags to persist information across sessions:

<remember>Important info here</remember>           <!-- 7 days -->
<remember priority>Critical info here</remember>  <!-- Permanent -->

What to capture:

• Architecture decisions
• Error resolutions
• User preferences

What NOT to capture:

• Progress (use todos instead)
• Info already in AGENTS.md