OMC Setup

•
2.1k
•

Configures and initializes the oh-my-claudecode orchestration framework to enable multi-agent execution modes and automated workflows.

OMC Setup is the primary entry point for the oh-my-claudecode plugin, serving as a comprehensive installation wizard and configuration manager. It automates the complex task of setting up project-specific or global CLAUDE.md files, installing the HUD status line for real-time agent monitoring, and clearing stale caches to ensure peak performance. By managing the underlying orchestration settings and execution mode preferences, this skill eliminates the manual boilerplate required to enable advanced features like Autopilot, Swarm, and Parallel execution in Claude Code.

Características Principales

01HUD status line installation for real-time monitoring of agent states
02Configuration of default execution modes including Ultrawork and Ecomode
03Guided wizard for local project or global system-wide configuration
042,142 GitHub stars
05Automated retrieval of the latest CLAUDE.md orchestration guidelines via curl
06Intelligent detection and cleanup of legacy version hooks and plugin caches

Casos de Uso

01Upgrading existing oh-my-claudecode installations to the latest version
02Initial environment setup for multi-agent orchestration in Claude Code
03Standardizing AI behaviors and rules across multiple development projects
name description
omc-setup
Setup and configure oh-my-claudecode (the ONLY command you need to learn)

OMC Setup

This is the only command you need to learn. After running this, everything else is automatic.

Usage Modes

This skill handles three scenarios:

  1. Initial Setup (no flags): First-time installation wizard
  2. Local Configuration (--local): Configure project-specific settings (.claude/CLAUDE.md)
  3. Global Configuration (--global): Configure global settings (~/.claude/CLAUDE.md)

Mode Detection

Check for flags in the user's invocation:

  • If --local flag present → Skip to Local Configuration (Step 2A)
  • If --global flag present → Skip to Global Configuration (Step 2B)
  • If no flags → Run Initial Setup wizard (Step 1)

Step 1: Initial Setup Wizard (Default Behavior)

Use the AskUserQuestion tool to prompt the user:

Question: "Where should I configure oh-my-claudecode?"

Options:

  1. Local (this project) - Creates .claude/CLAUDE.md in current project directory. Best for project-specific configurations.
  2. Global (all projects) - Creates ~/.claude/CLAUDE.md for all Claude Code sessions. Best for consistent behavior everywhere.

Step 2A: Local Configuration (--local flag or user chose LOCAL)

CRITICAL: This ALWAYS downloads fresh CLAUDE.md from GitHub to the local project. DO NOT use the Write tool - use bash curl exclusively.

Create Local .claude Directory

# Create .claude directory in current project
mkdir -p .claude && echo ".claude directory ready"

Download Fresh CLAUDE.md

# Extract old version before download
OLD_VERSION=$(grep -m1 "^# oh-my-claudecode" .claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")

# Download fresh CLAUDE.md from GitHub
curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o .claude/CLAUDE.md && \
echo "Downloaded CLAUDE.md to .claude/CLAUDE.md"

# Extract new version and report
NEW_VERSION=$(grep -m1 "^# oh-my-claudecode" .claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
if [ "$OLD_VERSION" = "none" ]; then
  echo "Installed CLAUDE.md: $NEW_VERSION"
elif [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
  echo "CLAUDE.md unchanged: $NEW_VERSION"
else
  echo "Updated CLAUDE.md: $OLD_VERSION -> $NEW_VERSION"
fi

Note: The downloaded CLAUDE.md includes Context Persistence instructions with <remember> tags for surviving conversation compaction.

MANDATORY: Always run this command. Do NOT skip. Do NOT use Write tool.

FALLBACK if curl fails: Tell user to manually download from: https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md

Verify Plugin Installation

grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"

Confirm Local Configuration Success

After completing local configuration, report:

OMC Project Configuration Complete

  • CLAUDE.md: Updated with latest configuration from GitHub at ./.claude/CLAUDE.md
  • Scope: PROJECT - applies only to this project
  • Hooks: Provided by plugin (no manual installation needed)
  • Agents: 28+ available (base + tiered variants)
  • Model routing: Haiku/Sonnet/Opus based on task complexity

Note: This configuration is project-specific and won't affect other projects or global settings.

If --local flag was used, STOP HERE. Do not continue to HUD setup or other steps.

Step 2B: Global Configuration (--global flag or user chose GLOBAL)

CRITICAL: This ALWAYS downloads fresh CLAUDE.md from GitHub to global config. DO NOT use the Write tool - use bash curl exclusively.

Download Fresh CLAUDE.md

# Extract old version before download
OLD_VERSION=$(grep -m1 "^# oh-my-claudecode" ~/.claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "none")

# Download fresh CLAUDE.md to global config
curl -fsSL "https://raw.githubusercontent.com/Yeachan-Heo/oh-my-claudecode/main/docs/CLAUDE.md" -o ~/.claude/CLAUDE.md && \
echo "Downloaded CLAUDE.md to ~/.claude/CLAUDE.md"

# Extract new version and report
NEW_VERSION=$(grep -m1 "^# oh-my-claudecode" ~/.claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
if [ "$OLD_VERSION" = "none" ]; then
  echo "Installed CLAUDE.md: $NEW_VERSION"
elif [ "$OLD_VERSION" = "$NEW_VERSION" ]; then
  echo "CLAUDE.md unchanged: $NEW_VERSION"
else
  echo "Updated CLAUDE.md: $OLD_VERSION -> $NEW_VERSION"
fi

Clean Up Legacy Hooks (if present)

Check if old manual hooks exist and remove them to prevent duplicates:

# Remove legacy bash hook scripts (now handled by plugin system)
rm -f ~/.claude/hooks/keyword-detector.sh
rm -f ~/.claude/hooks/stop-continuation.sh
rm -f ~/.claude/hooks/persistent-mode.sh
rm -f ~/.claude/hooks/session-start.sh
echo "Legacy hooks cleaned"

Check ~/.claude/settings.json for manual hook entries. If the "hooks" key exists with UserPromptSubmit, Stop, or SessionStart entries pointing to bash scripts, inform the user:

Note: Found legacy hooks in settings.json. These should be removed since the plugin now provides hooks automatically. Remove the "hooks" section from ~/.claude/settings.json to prevent duplicate hook execution.

Verify Plugin Installation

grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"

Confirm Global Configuration Success

After completing global configuration, report:

OMC Global Configuration Complete

  • CLAUDE.md: Updated with latest configuration from GitHub at ~/.claude/CLAUDE.md
  • Scope: GLOBAL - applies to all Claude Code sessions
  • Hooks: Provided by plugin (no manual installation needed)
  • Agents: 28+ available (base + tiered variants)
  • Model routing: Haiku/Sonnet/Opus based on task complexity

Note: Hooks are now managed by the plugin system automatically. No manual hook installation required.

If --global flag was used, STOP HERE. Do not continue to HUD setup or other steps.

Step 3: Setup HUD Statusline

The HUD shows real-time status in Claude Code's status bar. Invoke the hud skill to set up and configure:

Use the Skill tool to invoke: hud with args: setup

This will:

  1. Install the HUD wrapper script to ~/.claude/hud/omc-hud.mjs
  2. Configure statusLine in ~/.claude/settings.json
  3. Report status and prompt to restart if needed

Step 3.5: Clear Stale Plugin Cache

Clear old cached plugin versions to avoid conflicts:

# Clear stale plugin cache versions
CACHE_DIR="$HOME/.claude/plugins/cache/omc/oh-my-claudecode"
if [ -d "$CACHE_DIR" ]; then
  LATEST=$(ls -1 "$CACHE_DIR" | sort -V | tail -1)
  CLEARED=0
  for dir in "$CACHE_DIR"/*; do
    if [ "$(basename "$dir")" != "$LATEST" ]; then
      rm -rf "$dir"
      CLEARED=$((CLEARED + 1))
    fi
  done
  [ $CLEARED -gt 0 ] && echo "Cleared $CLEARED stale cache version(s)" || echo "Cache is clean"
else
  echo "No cache directory found (normal for new installs)"
fi

Step 3.6: Check for Updates

Notify user if a newer version is available:

# Detect installed version
INSTALLED_VERSION=""

# Try cache directory first
if [ -d "$HOME/.claude/plugins/cache/omc/oh-my-claudecode" ]; then
  INSTALLED_VERSION=$(ls -1 "$HOME/.claude/plugins/cache/omc/oh-my-claudecode" | sort -V | tail -1)
fi

# Try .omc-version.json second
if [ -z "$INSTALLED_VERSION" ] && [ -f ".omc-version.json" ]; then
  INSTALLED_VERSION=$(grep -oE '"version":\s*"[^"]+' .omc-version.json | cut -d'"' -f4)
fi

# Try CLAUDE.md header third (local first, then global)
if [ -z "$INSTALLED_VERSION" ]; then
  if [ -f ".claude/CLAUDE.md" ]; then
    INSTALLED_VERSION=$(grep -m1 "^# oh-my-claudecode" .claude/CLAUDE.md 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | sed 's/^v//')
  elif [ -f "$HOME/.claude/CLAUDE.md" ]; then
    INSTALLED_VERSION=$(grep -m1 "^# oh-my-claudecode" "$HOME/.claude/CLAUDE.md" 2>/dev/null | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' | sed 's/^v//')
  fi
fi

# Check npm for latest version
LATEST_VERSION=$(npm view oh-my-claude-sisyphus version 2>/dev/null)

if [ -n "$INSTALLED_VERSION" ] && [ -n "$LATEST_VERSION" ]; then
  # Simple version comparison (assumes semantic versioning)
  if [ "$INSTALLED_VERSION" != "$LATEST_VERSION" ]; then
    echo ""
    echo "UPDATE AVAILABLE:"
    echo "  Installed: v$INSTALLED_VERSION"
    echo "  Latest:    v$LATEST_VERSION"
    echo ""
    echo "To update, run: claude /install-plugin oh-my-claudecode"
  else
    echo "You're on the latest version: v$INSTALLED_VERSION"
  fi
elif [ -n "$LATEST_VERSION" ]; then
  echo "Latest version available: v$LATEST_VERSION"
fi

Step 3.7: Set Default Execution Mode

Use the AskUserQuestion tool to prompt the user:

Question: "Which parallel execution mode should be your default when you say 'fast' or 'parallel'?"

Options:

  1. ultrawork (maximum capability) - Uses all agent tiers including Opus for complex tasks. Best for challenging work where quality matters most. (Recommended)
  2. ecomode (token efficient) - Prefers Haiku/Sonnet agents, avoids Opus. Best for pro-plan users who want cost efficiency.

Store the preference in ~/.claude/.omc-config.json:

# Read existing config or create empty object
CONFIG_FILE="$HOME/.claude/.omc-config.json"
mkdir -p "$(dirname "$CONFIG_FILE")"

if [ -f "$CONFIG_FILE" ]; then
  EXISTING=$(cat "$CONFIG_FILE")
else
  EXISTING='{}'
fi

# Set defaultExecutionMode (replace USER_CHOICE with "ultrawork" or "ecomode")
echo "$EXISTING" | jq --arg mode "USER_CHOICE" '. + {defaultExecutionMode: $mode, configuredAt: (now | todate)}' > "$CONFIG_FILE"
echo "Default execution mode set to: USER_CHOICE"

Note: This preference ONLY affects generic keywords ("fast", "parallel"). Explicit keywords ("ulw", "eco") always override this preference.

Step 4: Verify Plugin Installation

grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"

Step 5: Offer MCP Server Configuration

MCP servers extend Claude Code with additional tools (web search, GitHub, etc.).

Ask user: "Would you like to configure MCP servers for enhanced capabilities? (Context7, Exa search, GitHub, etc.)"

If yes, invoke the mcp-setup skill:

/oh-my-claudecode:mcp-setup

If no, skip to next step.

Step 6: Detect Upgrade from 2.x

Check if user has existing configuration:

# Check for existing 2.x artifacts
ls ~/.claude/commands/ralph-loop.md 2>/dev/null || ls ~/.claude/commands/ultrawork.md 2>/dev/null

If found, this is an upgrade from 2.x.

Step 7: Show Welcome Message

For New Users:

OMC Setup Complete!

You don't need to learn any commands. I now have intelligent behaviors that activate automatically.

WHAT HAPPENS AUTOMATICALLY:
- Complex tasks -> I parallelize and delegate to specialists
- "plan this" -> I start a planning interview
- "don't stop until done" -> I persist until verified complete
- "stop" or "cancel" -> I intelligently stop current operation

MAGIC KEYWORDS (optional power-user shortcuts):
Just include these words naturally in your request:

| Keyword | Effect | Example |
|---------|--------|---------|
| ralph | Persistence mode | "ralph: fix the auth bug" |
| ralplan | Iterative planning | "ralplan this feature" |
| ulw | Max parallelism | "ulw refactor the API" |
| eco | Token-efficient mode | "eco refactor the API" |
| plan | Planning interview | "plan the new endpoints" |

Combine them: "ralph ulw: migrate the database"

MCP SERVERS:
Run /oh-my-claudecode:mcp-setup to add tools like web search, GitHub, etc.

HUD STATUSLINE:
The status bar now shows OMC state. Restart Claude Code to see it.

That's it! Just use Claude Code normally.

For Users Upgrading from 2.x:

OMC Setup Complete! (Upgraded from 2.x)

GOOD NEWS: Your existing commands still work!
- /ralph, /ultrawork, /planner, etc. all still function

WHAT'S NEW in 3.0:
You no longer NEED those commands. Everything is automatic now:
- Just say "don't stop until done" instead of /ralph
- Just say "fast" or "parallel" instead of /ultrawork
- Just say "plan this" instead of /planner
- Just say "stop" instead of /cancel-ralph

MAGIC KEYWORDS (power-user shortcuts):
| Keyword | Same as old... | Example |
|---------|----------------|---------|
| ralph | /ralph | "ralph: fix the bug" |
| ralplan | /ralplan | "ralplan this feature" |
| ulw | /ultrawork | "ulw refactor API" |
| eco | (new!) | "eco fix all errors" |
| plan | /planner | "plan the endpoints" |

HUD STATUSLINE:
The status bar now shows OMC state. Restart Claude Code to see it.

Your workflow won't break - it just got easier!

Step 8: Ask About Starring Repository

First, check if gh CLI is available and authenticated:

gh auth status &>/dev/null

If gh is available and authenticated:

Use the AskUserQuestion tool to prompt the user:

Question: "If you're enjoying oh-my-claudecode, would you like to support the project by starring it on GitHub?"

Options:

  1. Yes, star it! - Star the repository
  2. No thanks - Skip without further prompts
  3. Maybe later - Skip without further prompts

If user chooses "Yes, star it!":

gh api -X PUT /user/starred/Yeachan-Heo/oh-my-claudecode 2>/dev/null && echo "Thanks for starring! ⭐" || true

Note: Fail silently if the API call doesn't work - never block setup completion.

If gh is NOT available or not authenticated:

echo ""
echo "If you enjoy oh-my-claudecode, consider starring the repo:"
echo "  https://github.com/Yeachan-Heo/oh-my-claudecode"
echo ""

Keeping Up to Date

After installing oh-my-claudecode updates (via npm or plugin update), run:

  • /oh-my-claudecode:omc-setup --local to update project config
  • /oh-my-claudecode:omc-setup --global to update global config

This ensures you have the newest features and agent configurations.

Help Text

When user runs /oh-my-claudecode:omc-setup --help or just --help, display:

OMC Setup - Configure oh-my-claudecode

USAGE:
  /oh-my-claudecode:omc-setup           Run initial setup wizard
  /oh-my-claudecode:omc-setup --local   Configure local project (.claude/CLAUDE.md)
  /oh-my-claudecode:omc-setup --global  Configure global settings (~/.claude/CLAUDE.md)
  /oh-my-claudecode:omc-setup --help    Show this help

MODES:
  Initial Setup (no flags)
    - Interactive wizard for first-time setup
    - Configures CLAUDE.md (local or global)
    - Sets up HUD statusline
    - Checks for updates
    - Offers MCP server configuration

  Local Configuration (--local)
    - Downloads fresh CLAUDE.md to ./.claude/
    - Project-specific settings
    - Use this to update project config after OMC upgrades

  Global Configuration (--global)
    - Downloads fresh CLAUDE.md to ~/.claude/
    - Applies to all Claude Code sessions
    - Cleans up legacy hooks
    - Use this to update global config after OMC upgrades

EXAMPLES:
  /oh-my-claudecode:omc-setup           # First time setup
  /oh-my-claudecode:omc-setup --local   # Update this project
  /oh-my-claudecode:omc-setup --global  # Update all projects

For more info: https://github.com/Yeachan-Heo/oh-my-claudecode