From oh-my-claudecode
Setup and configure oh-my-claudecode (the ONLY command you need to learn)
How this skill is triggered — by the user, by Claude, or both
Slash command
/oh-my-claudecode:omc-setupThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This is the **only command you need to learn**. After running this, everything else is automatic.
This is the only command you need to learn. After running this, everything else is automatic.
IMPORTANT: This setup process saves progress after each step. If interrupted (Ctrl+C or connection loss), the setup can resume from where it left off.
.omc/state/setup-state.json - Tracks completed stepsBefore starting any step, check for existing state:
# Check for existing setup state
STATE_FILE=".omc/state/setup-state.json"
# Cross-platform ISO date to epoch conversion
iso_to_epoch() {
local iso_date="$1"
local epoch=""
# Try GNU date first (Linux)
epoch=$(date -d "$iso_date" +%s 2>/dev/null)
if [ $? -eq 0 ] && [ -n "$epoch" ]; then
echo "$epoch"
return 0
fi
# Try BSD/macOS date
local clean_date=$(echo "$iso_date" | sed 's/[+-][0-9][0-9]:[0-9][0-9]$//' | sed 's/Z$//' | sed 's/T/ /')
epoch=$(date -j -f "%Y-%m-%d %H:%M:%S" "$clean_date" +%s 2>/dev/null)
if [ $? -eq 0 ] && [ -n "$epoch" ]; then
echo "$epoch"
return 0
fi
echo "0"
}
if [ -f "$STATE_FILE" ]; then
# Check if state is stale (older than 24 hours)
TIMESTAMP_RAW=$(jq -r '.timestamp // empty' "$STATE_FILE" 2>/dev/null)
if [ -n "$TIMESTAMP_RAW" ]; then
TIMESTAMP_EPOCH=$(iso_to_epoch "$TIMESTAMP_RAW")
NOW_EPOCH=$(date +%s)
STATE_AGE=$((NOW_EPOCH - TIMESTAMP_EPOCH))
else
STATE_AGE=999999 # Force fresh start if no timestamp
fi
if [ "$STATE_AGE" -gt 86400 ]; then
echo "Previous setup state is more than 24 hours old. Starting fresh."
rm -f "$STATE_FILE"
else
LAST_STEP=$(jq -r ".lastCompletedStep // 0" "$STATE_FILE" 2>/dev/null || echo "0")
TIMESTAMP=$(jq -r .timestamp "$STATE_FILE" 2>/dev/null || echo "unknown")
echo "Found previous setup session (Step $LAST_STEP completed at $TIMESTAMP)"
fi
fi
If state exists, use AskUserQuestion to prompt:
Question: "Found a previous setup session. Would you like to resume or start fresh?"
Options:
If user chooses "Start fresh":
rm -f ".omc/state/setup-state.json"
echo "Previous state cleared. Starting fresh setup."
After completing each major step, save progress:
# Save setup progress (call after each step)
# Usage: save_setup_progress STEP_NUMBER
save_setup_progress() {
mkdir -p .omc/state
cat > ".omc/state/setup-state.json" << EOF
{
"lastCompletedStep": $1,
"timestamp": "$(date -Iseconds)",
"configType": "${CONFIG_TYPE:-unknown}"
}
EOF
}
After successful setup completion (Step 7/8), remove the state file:
rm -f ".omc/state/setup-state.json"
echo "Setup completed successfully. State cleared."
This skill handles three scenarios:
--local): Configure project-specific settings (.claude/CLAUDE.md)--global): Configure global settings (~/.claude/CLAUDE.md)Check for flags in the user's invocation:
--local flag present → Skip to Local Configuration (Step 2A)--global flag present → Skip to Global Configuration (Step 2B)Note: If resuming and lastCompletedStep >= 1, skip to the appropriate step based on configType.
Use the AskUserQuestion tool to prompt the user:
Question: "Where should I configure oh-my-claudecode?"
Options:
.claude/CLAUDE.md in current project directory. Best for project-specific configurations.~/.claude/CLAUDE.md for all Claude Code sessions. Best for consistent behavior everywhere.CRITICAL: This ALWAYS downloads fresh CLAUDE.md from GitHub to the local project. DO NOT use the Write tool - use bash curl exclusively.
# Create .claude directory in current project
mkdir -p .claude && echo ".claude directory ready"
# 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")
# Backup existing CLAUDE.md before overwriting (if it exists)
if [ -f ".claude/CLAUDE.md" ]; then
BACKUP_DATE=$(date +%Y-%m-%d)
BACKUP_PATH=".claude/CLAUDE.md.backup.${BACKUP_DATE}"
cp .claude/CLAUDE.md "$BACKUP_PATH"
echo "Backed up existing CLAUDE.md to $BACKUP_PATH"
fi
# 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.
Note: If an existing CLAUDE.md is found, it will be backed up to .claude/CLAUDE.md.backup.YYYY-MM-DD before downloading the new version.
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
grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"
After completing local configuration, save progress and report:
# Save progress - Step 2 complete (Local config)
mkdir -p .omc/state
cat > ".omc/state/setup-state.json" << EOF
{
"lastCompletedStep": 2,
"timestamp": "$(date -Iseconds)",
"configType": "local"
}
EOF
OMC Project Configuration Complete
.claude/CLAUDE.md.backup.YYYY-MM-DD (if existed)Note: This configuration is project-specific and won't affect other projects or global settings.
If --local flag was used, clear state and STOP HERE:
rm -f ".omc/state/setup-state.json"
Do not continue to HUD setup or other steps.
CRITICAL: This ALWAYS downloads fresh CLAUDE.md from GitHub to global config. DO NOT use the Write tool - use bash curl exclusively.
# 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")
# Backup existing CLAUDE.md before overwriting (if it exists)
if [ -f "$HOME/.claude/CLAUDE.md" ]; then
BACKUP_DATE=$(date +%Y-%m-%d)
BACKUP_PATH="$HOME/.claude/CLAUDE.md.backup.${BACKUP_DATE}"
cp "$HOME/.claude/CLAUDE.md" "$BACKUP_PATH"
echo "Backed up existing CLAUDE.md to $BACKUP_PATH"
fi
# 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
Note: If an existing CLAUDE.md is found, it will be backed up to ~/.claude/CLAUDE.md.backup.YYYY-MM-DD before downloading the new version.
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.
grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"
After completing global configuration, save progress and report:
# Save progress - Step 2 complete (Global config)
mkdir -p .omc/state
cat > ".omc/state/setup-state.json" << EOF
{
"lastCompletedStep": 2,
"timestamp": "$(date -Iseconds)",
"configType": "global"
}
EOF
OMC Global Configuration Complete
~/.claude/CLAUDE.md.backup.YYYY-MM-DD (if existed)Note: Hooks are now managed by the plugin system automatically. No manual hook installation required.
If --global flag was used, clear state and STOP HERE:
rm -f ".omc/state/setup-state.json"
Do not continue to HUD setup or other steps.
Note: If resuming and lastCompletedStep >= 3, skip to Step 3.5.
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:
~/.claude/hud/omc-hud.mjsstatusLine in ~/.claude/settings.jsonAfter HUD setup completes, save progress:
# Save progress - Step 3 complete (HUD setup)
mkdir -p .omc/state
CONFIG_TYPE=$(cat ".omc/state/setup-state.json" 2>/dev/null | grep -oE '"configType":\s*"[^"]+"' | cut -d'"' -f4 || echo "unknown")
cat > ".omc/state/setup-state.json" << EOF
{
"lastCompletedStep": 3,
"timestamp": "$(date -Iseconds)",
"configType": "$CONFIG_TYPE"
}
EOF
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
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
Use the AskUserQuestion tool to prompt the user:
Question: "Which parallel execution mode should be your default when you say 'fast' or 'parallel'?"
Options:
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.
The OMC CLI provides standalone token analytics commands (omc stats, omc agents, omc tui).
Ask user: "Would you like to install the OMC CLI for standalone analytics? (Recommended for tracking token usage and costs)"
Options:
omc stats, omc agents, etc.# Check for bun (preferred) or npm
if command -v bun &> /dev/null; then
echo "Installing OMC CLI via bun..."
bun install -g oh-my-claude-sisyphus
elif command -v npm &> /dev/null; then
echo "Installing OMC CLI via npm..."
npm install -g oh-my-claude-sisyphus
else
echo "ERROR: Neither bun nor npm found. Please install Node.js or Bun first."
exit 1
fi
# Verify installation
if command -v omc &> /dev/null; then
echo "✓ OMC CLI installed successfully!"
echo " Try: omc stats, omc agents, omc tui"
else
echo "⚠ CLI installed but 'omc' not in PATH."
echo " You may need to restart your terminal or add npm/bun global bin to PATH."
fi
Skip this step. User can install later with npm install -g oh-my-claude-sisyphus.
grep -q "oh-my-claudecode" ~/.claude/settings.json && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"
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.
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.
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.
CLI ANALYTICS (if installed):
- omc - Full dashboard (stats + agents + cost)
- omc stats - View token usage and costs
- omc agents - See agent breakdown by cost
- omc tui - Launch interactive TUI dashboard
That's it! Just use Claude Code normally.
OMC Setup Complete! (Upgraded from 2.x)
GOOD NEWS: Your existing commands still work!
- /ralph, /ultrawork, /plan, 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 /plan
- Just say "stop" instead of /cancel
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 | /plan | "plan the endpoints" |
HUD STATUSLINE:
The status bar now shows OMC state. Restart Claude Code to see it.
CLI ANALYTICS (if installed):
- omc - Full dashboard (stats + agents + cost)
- omc stats - View token usage and costs
- omc agents - See agent breakdown by cost
- omc tui - Launch interactive TUI dashboard
Your workflow won't break - it just got easier!
First, check if gh CLI is available and authenticated:
gh auth status &>/dev/null
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:
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.
echo ""
echo "If you enjoy oh-my-claudecode, consider starring the repo:"
echo " https://github.com/Yeachan-Heo/oh-my-claudecode"
echo ""
After Step 8 completes (regardless of star choice), clear the setup state:
# Setup complete - clear state file
rm -f ".omc/state/setup-state.json"
echo "Setup completed successfully!"
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 configThis ensures you have the newest features and agent configurations.
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/
- Backs up existing CLAUDE.md to .claude/CLAUDE.md.backup.YYYY-MM-DD
- Project-specific settings
- Use this to update project config after OMC upgrades
Global Configuration (--global)
- Downloads fresh CLAUDE.md to ~/.claude/
- Backs up existing CLAUDE.md to ~/.claude/CLAUDE.md.backup.YYYY-MM-DD
- 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
npx claudepluginhub letrandat/oh-my-claudecodeGuides collaborative design exploration before implementation: explores context, asks clarifying questions, proposes approaches, and writes a design doc for user approval.
Creates structured, bite-sized implementation plans from specs or requirements before writing code. Useful for breaking down multi-step tasks into testable steps with file structure and task boundaries.
Provides Slack GIF creation utilities with dimension/FPS/color constraints and Python PIL-based frame generation. Use for animated Slack emoji or message GIFs.
2plugins reuse this skill
First indexed Jul 8, 2026