Omc Setup

OMC Setup

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

When this skill is invoked, immediately execute the workflow below. Do not only restate or summarize these instructions back to the user.

Note: All ~/.claude/... paths in this guide respect CLAUDE_CONFIG_DIR when that environment variable is set.

Best-Fit Use

Choose this setup flow when the user wants to install, refresh, or repair OMC itself.

• Marketplace/plugin install users should land here after /plugin install oh-my-claudecode
• npm users should land here after npm i -g oh-my-claude-sisyphus@latest
• local-dev and worktree users should land here after updating the checked-out repo and rerunning setup

Flag Parsing

Check for flags in the user's invocation:

• --help → Show Help Text (below) and stop
• --local → Phase 1 only (target=local), then stop
• --global → Phase 1 only (target=global), then stop
• --force → Skip Pre-Setup Check, run full setup (Phase 1 → 2 → 3 → 4)
• No flags → Run Pre-Setup Check, then full setup if needed

Help Text

When user runs with --help, display this and stop:

OMC Setup - Configure oh-my-claudecode

USAGE:
  /oh-my-claudecode:omc-setup           Run initial setup wizard (or update if already configured)
  /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 --force   Force full setup wizard even if already configured
  /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
    - Configures team mode defaults (agent count, type, model)
    - If already configured, offers quick update option

  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
    - Default: explicitly overwrites ~/.claude/CLAUDE.md so plain `claude` also uses OMC
    - Optional preserve mode keeps the user's base `CLAUDE.md` and installs OMC into `CLAUDE-omc.md` for `omc` launches
    - Applies to all Claude Code sessions
    - Cleans up legacy hooks
    - Use this to update global config after OMC upgrades

  Force Full Setup (--force)
    - Bypasses the "already configured" check
    - Runs the complete setup wizard from scratch
    - Use when you want to reconfigure preferences

EXAMPLES:
  /oh-my-claudecode:omc-setup           # First time setup (or update CLAUDE.md if configured)
  /oh-my-claudecode:omc-setup --local   # Update this project
  /oh-my-claudecode:omc-setup --global  # Update all projects
  /oh-my-claudecode:omc-setup --force   # Re-run full setup wizard

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

Active Plugin Root Resolution

Before running setup shell commands or reading phase files, resolve the current OMC plugin root. This prevents an already-running Claude Code session from continuing to use a stale CLAUDE_PLUGIN_ROOT after /plugin marketplace update omc installs a newer cache version.

OMC_SETUP_PLUGIN_ROOT=$(node -e "const f=require('fs'),p=require('path'),h=require('os').homedir(),d=(process.env.CLAUDE_CONFIG_DIR||p.join(h,'.claude')).replace(/[\\/]+$/,''),b=p.join(d,'plugins','cache','omc','oh-my-claudecode'),valid=r=>f.existsSync(p.join(r,'skills','omc-setup','SKILL.md'))||f.existsSync(p.join(r,'hooks','hooks.json'))||f.existsSync(p.join(r,'docs','CLAUDE.md'));try{const vs=f.readdirSync(b,{withFileTypes:true}).filter(e=>(e.isDirectory()||e.isSymbolicLink())&&/^\d+\.\d+\.\d+/.test(e.name)).map(e=>e.name).sort((a,c)=>c.localeCompare(a,void 0,{numeric:true}));const hit=vs.map(v=>p.join(b,v)).find(valid);if(hit)console.log(hit);else if(process.env.CLAUDE_PLUGIN_ROOT)console.log(process.env.CLAUDE_PLUGIN_ROOT)}catch{if(process.env.CLAUDE_PLUGIN_ROOT)console.log(process.env.CLAUDE_PLUGIN_ROOT)}")
export OMC_SETUP_PLUGIN_ROOT

Use ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}} for all setup script and phase paths, then immediately repair stale cache references before any prompts or phase work:

node "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/repair-plugin-cache.mjs"

Pre-Setup Check: Already Configured?

CRITICAL: Before doing anything else, check if setup has already been completed. This prevents users from having to re-run the full setup wizard after every update.

# Check if setup was already completed
CONFIG_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.omc-config.json"

if [ -f "$CONFIG_FILE" ]; then
  SETUP_COMPLETED=$(jq -r '.setupCompleted // empty' "$CONFIG_FILE" 2>/dev/null)
  SETUP_VERSION=$(jq -r '.setupVersion // empty' "$CONFIG_FILE" 2>/dev/null)

  if [ -n "$SETUP_COMPLETED" ] && [ "$SETUP_COMPLETED" != "null" ]; then
    echo "OMC setup was already completed on: $SETUP_COMPLETED"
    [ -n "$SETUP_VERSION" ] && echo "Setup version: $SETUP_VERSION"
    ALREADY_CONFIGURED="true"
  fi
fi

If Already Configured (and no --force flag)

If ALREADY_CONFIGURED is true AND the user did NOT pass --force, --local, or --global flags:

Use AskUserQuestion to prompt:

Question: "OMC is already configured. What would you like to do?"

Options: 1. Update CLAUDE.md only - Download latest CLAUDE.md without re-running full setup 2. Run full setup again - Go through the complete setup wizard 3. Cancel - Exit without changes

If user chooses "Update CLAUDE.md only":

• Detect if local (.claude/CLAUDE.md) or global (~/.claude/CLAUDE.md) config exists
• If local exists, run: bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" local
• If only global exists, run: bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" global
• Skip all other steps
• Report success and exit

If user chooses "Run full setup again":

• Continue with Resume Detection below

If user chooses "Cancel":

• Exit without any changes

Force Flag Override

If user passes --force flag, skip this check and proceed directly to setup.

Resume Detection

Before starting any phase, check for existing state:

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" resume

If state exists (output is not "fresh"), use AskUserQuestion to prompt:

Question: "Found a previous setup session. Would you like to resume or start fresh?"

Options: 1. Resume from step $LAST_STEP - Continue where you left off 2. Start fresh - Begin from the beginning (clears saved state)

If user chooses "Start fresh":

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" clear

Phase Execution

For --local or --global flags:

Read the file at ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/01-install-claude-md.md and follow its instructions. (The phase file handles early exit for flag mode.)

For full setup (default or --force):

Execute phases sequentially. For each phase, read the corresponding file and follow its instructions:

1. Phase 1 - Install CLAUDE.md: Read ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/01-install-claude-md.md and follow its instructions.

2. Phase 2 - Environment Configuration: Read ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/02-configure.md and follow its instructions. Phase 2 must delegate HUD/statusLine setup to the hud skill; do not generate or patch statusLine paths inline here.

3. Phase 3 - Integration Setup: Read ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/03-integrations.md and follow its instructions.

4. Phase 4 - Completion: Read ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/04-welcome.md and follow its instructions.

Graceful Interrupt Handling

IMPORTANT: This setup process saves progress after each phase via ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh. If interrupted (Ctrl+C or connection loss), the setup can resume from where it left off.

Keeping Up to Date

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

Automatic: Just run /oh-my-claudecode:omc-setup - it will detect you've already configured and offer a quick "Update CLAUDE.md only" option that skips the full wizard.

Manual options:

• /oh-my-claudecode:omc-setup --local to update project config only
• /oh-my-claudecode:omc-setup --global to update global config only
• /oh-my-claudecode:omc-setup --force to re-run the full wizard (reconfigure preferences)

This ensures you have the newest features and agent configurations without the token cost of repeating the full setup.

Phase 1: Install CLAUDE.md

Determine Configuration Target

If --local flag was passed, set CONFIG_TARGET=local. If --global flag was passed, set CONFIG_TARGET=global.

Otherwise (initial setup wizard), use AskUserQuestion to prompt:

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.

Set CONFIG_TARGET to local or global based on user's choice.

If CONFIG_TARGET=global and ~/.claude/CLAUDE.md already exists without OMC markers, ask a second explicit question before running setup:

Question: "Global setup will change your base Claude config. Which behavior do you want?"

Options (default first): 1. Overwrite base CLAUDE.md (Recommended) - plain claude and omc both use OMC globally. 2. Keep base CLAUDE.md; use OMC only through `omc` - preserve the user's base file, install OMC into CLAUDE-omc.md, and let omc force-load that companion config at launch.

Set GLOBAL_INSTALL_STYLE=overwrite or preserve based on the user's choice. If you did not ask this question, default GLOBAL_INSTALL_STYLE=overwrite.

Download and Install CLAUDE.md

MANDATORY: Always run this command. Do NOT skip. Do NOT use the Write tool. Let the setup script choose the safest canonical source (bundled docs/CLAUDE.md first, GitHub fallback only if needed).

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" <CONFIG_TARGET> [GLOBAL_INSTALL_STYLE]

Replace <CONFIG_TARGET> with local or global. For local installs, omit the optional style argument. For global installs, pass overwrite or preserve when you know the user's choice; otherwise let the script default to overwrite.

The script must install the canonical docs/CLAUDE.md content and preserve the required <!-- OMC:START --> / <!-- OMC:END --> markers. Do not hand-write, summarize, or partially reconstruct CLAUDE.md.

After running the script, verify the target file contains both markers. If marker validation fails, stop and report the failure instead of writing CLAUDE.md manually.

For local installs inside a git repository, the script also seeds .git/info/exclude with an OMC block that re-includes .omc/, ignores local .omc/* artifacts by default, and preserves .omc/skills/ for project skills you intend to commit.

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

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

Note: Preserve mode installs OMC into a companion CLAUDE-omc.md with a small managed import block, and omc launch force-loads that companion config without changing plain claude.

Report Success

If CONFIG_TARGET is local:

OMC Project Configuration Complete
- CLAUDE.md: Updated with latest configuration from GitHub at ./.claude/CLAUDE.md
- Git excludes: Added local `.omc/*` ignore rules to `.git/info/exclude` (keeps `.omc/skills/` trackable for committed project skills)
- Backup: Previous CLAUDE.md backed up (if existed)
- 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 CONFIG_TARGET is global:

OMC Global Configuration Complete
- CLAUDE.md: Updated at ~/.claude/CLAUDE.md, or preserved with explicit preserve mode
- Companion: May install ~/.claude/CLAUDE-omc.md when preserve mode is chosen
- Backup: Previous CLAUDE.md backed up (if existed)
- 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.

Save Progress

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" save 2 <CONFIG_TARGET>

Early Exit for Flag Mode

If --local or --global flag was used, clear state and STOP HERE:

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" clear

Do not continue to Phase 2 or other phases.

Phase 2: Environment Configuration

Skip condition: If resuming and lastCompletedStep >= 4, skip this entire phase.

Step 2.0: Check Ralph Ruby Dependency

Ralph workflows require Ruby. On fresh Ubuntu installations, missing Ruby can cause Ralph to fail later with an opaque Claude Code abort. Check for Ruby during setup and show a product-facing remediation hint without blocking the rest of setup:

if command -v ruby >/dev/null 2>&1; then
  echo "Ruby detected for Ralph workflows: $(ruby --version 2>/dev/null | head -1)"
else
  echo "WARNING: Ruby was not found on PATH. Ralph workflows require Ruby."
  echo "Install it, then restart Claude Code before using Ralph."
  echo "Ubuntu/Debian: sudo apt update && sudo apt install ruby-full"
  echo "macOS: brew install ruby"
fi

Step 2.1: Setup HUD Statusline

Note: If resuming and lastCompletedStep >= 3, skip to Step 2.2.

The HUD shows real-time status in Claude Code's status bar. Delegate all HUD/statusLine setup to the hud skill:

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

Do not generate, normalize, or patch statusLine paths inline in this phase. This is especially important on Windows, where backslash path handling must stay inside the hud skill.

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

After HUD setup completes, save progress:

CONFIG_TYPE=$(jq -r '.configType // "unknown"' ".omc/state/setup-state.json" 2>/dev/null || echo "unknown")
bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" save 3 "$CONFIG_TYPE"

Step 2.2: Repair Stale Plugin Cache References

After a marketplace update, Claude Code may still have old OMC cache paths in the running session or plugin registry. Repair those references before any cache cleanup so setup does not repeatedly emit stale plugin directory errors.

node "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/repair-plugin-cache.mjs"

Step 2.3: Check for Updates

Notify user if a newer version is available:

# Detect installed version (cross-platform)
node -e "
const p=require('path'),f=require('fs'),h=require('os').homedir();
const d=process.env.CLAUDE_CONFIG_DIR||p.join(h,'.claude');
let v='';
// Try cache directory first
const b=p.join(d,'plugins','cache','omc','oh-my-claudecode');
try{const vs=f.readdirSync(b).filter(x=>/^\d/.test(x)).sort((a,c)=>a.localeCompare(c,void 0,{numeric:true}));if(vs.length)v=vs[vs.length-1]}catch{}
// Try .omc-version.json second
if(v==='')try{const j=JSON.parse(f.readFileSync('.omc-version.json','utf-8'));v=j.version||''}catch{}
// Try CLAUDE.md header third
if(v==='')for(const c of['.claude/CLAUDE.md',p.join(d,'CLAUDE.md')]){try{const m=f.readFileSync(c,'utf-8').match(/^# oh-my-claudecode.*?(v?\d+\.\d+\.\d+)/m);if(m){v=m[1].replace(/^v/,'');break}}catch{}}
console.log('Installed:',v||'(not found)');
"

# 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
  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 2.4: 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)

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

CONFIG_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.omc-config.json"
mkdir -p "$(dirname "$CONFIG_FILE")"

if ! command -v jq >/dev/null 2>&1; then
  echo "ERROR: jq is required to update $CONFIG_FILE safely."
  echo "Install jq and rerun setup. Existing config was not modified."
  exit 1
fi

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

# Set defaultExecutionMode (replace USER_CHOICE with "ultrawork" or "")
TEMP_FILE=$(mktemp "${CONFIG_FILE}.tmp.XXXXXX")
trap 'rm -f "$TEMP_FILE"' EXIT
if printf '%s\n' "$EXISTING" | jq --arg mode "USER_CHOICE" '. + {defaultExecutionMode: $mode, configuredAt: (now | todate)}' > "$TEMP_FILE"; then
  mv "$TEMP_FILE" "$CONFIG_FILE"
else
  echo "ERROR: Failed to update $CONFIG_FILE. Existing config was not modified."
  exit 1
fi
trap - EXIT
echo "Default execution mode set to: USER_CHOICE"

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

Step 2.5: Install OMC CLI Tool

The OMC CLI (omc command) provides standalone helper commands such as omc hud, omc teleport, and omc team ....

First, check if the CLI is already installed:

if command -v omc &>/dev/null; then
  OMC_CLI_VERSION=$(omc --version 2>/dev/null | head -1 || echo "installed")
  echo "OMC CLI already installed: $OMC_CLI_VERSION"
  OMC_CLI_INSTALLED="true"
else
  OMC_CLI_INSTALLED="false"
fi

If OMC_CLI_INSTALLED is "true", skip the rest of this step.

If OMC_CLI_INSTALLED is "false", use AskUserQuestion:

Question: "Would you like to install the OMC CLI globally for standalone helper commands? (omc, omc hud, omc teleport)"

Options: 1. Yes (Recommended) - Install oh-my-claude-sisyphus via npm install -g 2. No - Skip - Skip installation (can install manually later with npm install -g oh-my-claude-sisyphus)

If user chooses Yes:

if ! command -v npm &>/dev/null; then
  echo "WARNING: npm not found. Cannot install OMC CLI automatically."
  echo "Install Node.js/npm first, then run: npm install -g oh-my-claude-sisyphus"
else
  if npm install -g oh-my-claude-sisyphus 2>&1; then
    echo "OMC CLI installed successfully."
    if command -v omc &>/dev/null; then
      OMC_CLI_VERSION=$(omc --version 2>/dev/null | head -1 || echo "installed")
      echo "Verified: omc $OMC_CLI_VERSION"
    else
      echo "Installed but 'omc' not on PATH. You may need to restart your shell."
    fi
  else
    echo "WARNING: Failed to install OMC CLI (permission issue or network error)."
    echo "You can install manually later: npm install -g oh-my-claude-sisyphus"
    echo "Or with sudo: sudo npm install -g oh-my-claude-sisyphus"
  fi
fi

Note: The CLI is optional. All core functionality is also available through the plugin system.

Step 2.6: Select Task Management Tool

First, detect available task tools:

BD_VERSION=""
if command -v bd &>/dev/null; then
  BD_VERSION=$(bd --version 2>/dev/null | head -1 || echo "installed")
fi

BR_VERSION=""
if command -v br &>/dev/null; then
  BR_VERSION=$(br --version 2>/dev/null | head -1 || echo "installed")
fi

if [ -n "$BD_VERSION" ]; then
  echo "Found beads (bd): $BD_VERSION"
fi
if [ -n "$BR_VERSION" ]; then
  echo "Found beads-rust (br): $BR_VERSION"
fi
if [ -z "$BD_VERSION" ] && [ -z "$BR_VERSION" ]; then
  echo "No external task tools found. Using built-in Tasks."
fi

If neither beads nor beads-rust is detected, skip this step (default to built-in).

If beads or beads-rust is detected, use AskUserQuestion:

Question: "Which task management tool should I use for tracking work?"

Options: 1. Built-in Tasks (default) - Use Claude Code's native TodoWrite or available task-list surface. Tasks are session-only. 2. Beads (bd) - Git-backed persistent tasks. Survives across sessions. [Only if detected] 3. Beads-Rust (br) - Lightweight Rust port of beads. [Only if detected]

(Only show options 2/3 if the corresponding tool is detected)

Store the preference:

CONFIG_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.omc-config.json"
mkdir -p "$(dirname "$CONFIG_FILE")"

if ! command -v jq >/dev/null 2>&1; then
  echo "ERROR: jq is required to update $CONFIG_FILE safely."
  echo "Install jq and rerun setup. Existing config was not modified."
  exit 1
fi

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

# USER_CHOICE is "builtin", "beads", or "beads-rust" based on user selection
TEMP_FILE=$(mktemp "${CONFIG_FILE}.tmp.XXXXXX")
trap 'rm -f "$TEMP_FILE"' EXIT
if printf '%s\n' "$EXISTING" | jq --arg tool "USER_CHOICE" '. + {taskTool: $tool, taskToolConfig: {injectInstructions: true, useMcp: false}}' > "$TEMP_FILE"; then
  mv "$TEMP_FILE" "$CONFIG_FILE"
else
  echo "ERROR: Failed to update $CONFIG_FILE. Existing config was not modified."
  exit 1
fi
trap - EXIT
echo "Task tool set to: USER_CHOICE"

Note: The beads context instructions will be injected automatically on the next session start.

Save Progress

CONFIG_TYPE=$(jq -r '.configType // "unknown"' ".omc/state/setup-state.json" 2>/dev/null || echo "unknown")
bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" save 4 "$CONFIG_TYPE"

Phase 3: Integration Setup

Skip condition: If resuming and lastCompletedStep >= 6, skip this entire phase.

Step 3.1: Verify Plugin Installation

grep -q "oh-my-claudecode" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json" && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"

Step 3.2: Offer MCP Server Configuration

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

Use AskUserQuestion: "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 3.3: Configure Agent Teams (Optional)

Agent teams are an experimental Claude Code feature that lets you spawn N coordinated agents working on a shared task list with inter-agent messaging. Teams are disabled by default and require enabling via settings.json.

Reference: https://code.claude.com/docs/en/agent-teams

Use AskUserQuestion:

Question: "Would you like to enable agent teams? Teams let you spawn coordinated agents (e.g., /team 3:executor 'fix all errors'). This is an experimental Claude Code feature."

Options: 1. Yes, enable teams (Recommended) - Enable the experimental feature and configure defaults 2. No, skip - Leave teams disabled (can enable later)

If User Chooses YES:

3.3.1: Enable Agent Teams in settings.json

CRITICAL: Agent teams require CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to be set in ~/.claude/settings.json. This must be done carefully to preserve existing user settings.

First, read the current settings.json:

SETTINGS_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"

if [ -f "$SETTINGS_FILE" ]; then
  echo "Current settings.json found"
  cat "$SETTINGS_FILE"
else
  echo "No settings.json found - will create one"
fi

Then use the Read tool to read ${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json (if it exists). Use the Edit tool to merge the teams configuration while preserving ALL existing settings.

Use jq to safely merge without overwriting existing settings:

SETTINGS_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"

if ! command -v jq >/dev/null 2>&1; then
  echo "ERROR: jq is required to update $SETTINGS_FILE safely."
  echo "Install jq and rerun setup. Existing settings were not modified."
  exit 1
fi

if [ -f "$SETTINGS_FILE" ]; then
  TEMP_FILE=$(mktemp "${SETTINGS_FILE}.tmp.XXXXXX")
  trap 'rm -f "$TEMP_FILE"' EXIT
  if jq '.env = (.env // {} | . + {"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"})' "$SETTINGS_FILE" > "$TEMP_FILE"; then
    mv "$TEMP_FILE" "$SETTINGS_FILE"
  else
    echo "ERROR: Failed to update $SETTINGS_FILE. Existing settings were not modified."
    exit 1
  fi
  trap - EXIT
  echo "Added CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to existing settings.json"
else
  mkdir -p "$(dirname "$SETTINGS_FILE")"
  cat > "$SETTINGS_FILE" << 'SETTINGS_EOF'
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
SETTINGS_EOF
  echo "Created settings.json with teams enabled"
fi

IMPORTANT: The Edit tool is preferred for modifying settings.json when possible, since it preserves formatting and comments. The jq approach above is the fallback for when the file needs structural merging.

3.3.2: Configure Teammate Display Mode

Use AskUserQuestion:

Question: "How should teammates be displayed?"

Options: 1. Auto (Recommended) - Uses split panes if in tmux, otherwise in-process. Best for most users. 2. In-process - All teammates in your main terminal. Use Shift+Up/Down to select. Works everywhere. 3. Split panes (tmux) - Each teammate in its own pane. Requires tmux or iTerm2.

If user chooses anything other than "Auto", add teammateMode to settings.json:

SETTINGS_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"

if ! command -v jq >/dev/null 2>&1; then
  echo "ERROR: jq is required to update $SETTINGS_FILE safely."
  echo "Install jq and rerun setup. Existing settings were not modified."
  exit 1
fi

# TEAMMATE_MODE is "in-process" or "tmux" based on user choice
# Skip this if user chose "Auto" (that's the default)
TEMP_FILE=$(mktemp "${SETTINGS_FILE}.tmp.XXXXXX")
trap 'rm -f "$TEMP_FILE"' EXIT
if jq --arg mode "TEAMMATE_MODE" '. + {teammateMode: $mode}' "$SETTINGS_FILE" > "$TEMP_FILE"; then
  mv "$TEMP_FILE" "$SETTINGS_FILE"
else
  echo "ERROR: Failed to update $SETTINGS_FILE. Existing settings were not modified."
  exit 1
fi
trap - EXIT
echo "Teammate display mode set to: TEAMMATE_MODE"

3.3.3: Configure Team Defaults in omc-config

Use AskUserQuestion with multiple questions:

Question 1: "How many agents should teams spawn by default?"

Options: 1. 3 agents (Recommended) - Good balance of speed and resource usage 2. 5 agents (maximum) - Maximum parallelism for large tasks 3. 2 agents - Conservative, for smaller projects

Question 2: "Which CLI provider should teammates use by default?"

Options: 1. claude (Recommended) - Default provider with the widest compatibility 2. codex - Use Codex CLI workers by default when installed 3. gemini - Use Gemini CLI workers by default when installed (enterprise/API-key tier) 4. antigravity - Use Antigravity CLI (agy) workers by default when installed; Google's successor to the Gemini CLI (install per the official instructions)

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

CONFIG_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.omc-config.json"
mkdir -p "$(dirname "$CONFIG_FILE")"

if ! command -v jq >/dev/null 2>&1; then
  echo "ERROR: jq is required to update $CONFIG_FILE safely."
  echo "Install jq and rerun setup. Existing config was not modified."
  exit 1
fi

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

# Replace MAX_AGENTS, AGENT_TYPE with user choices
TEMP_FILE=$(mktemp "${CONFIG_FILE}.tmp.XXXXXX")
trap 'rm -f "$TEMP_FILE"' EXIT
if printf '%s\n' "$EXISTING" | jq \
  --argjson maxAgents MAX_AGENTS \
  --arg agentType "AGENT_TYPE" \
  '. + {team: {ops: {maxAgents: $maxAgents, defaultAgentType: $agentType, monitorIntervalMs: 30000, shutdownTimeoutMs: 15000}}}' > "$TEMP_FILE"; then
  mv "$TEMP_FILE" "$CONFIG_FILE"
else
  echo "ERROR: Failed to update $CONFIG_FILE. Existing config was not modified."
  exit 1
fi
trap - EXIT

echo "Team configuration saved:"
echo "  Max agents: MAX_AGENTS"
echo "  Default provider: AGENT_TYPE"
echo "  Model: teammates inherit your session model"

Note: Teammates do not have a separate model default. Each teammate is a full Claude Code session that inherits your configured model. Subagents spawned by teammates can use any model tier.

Verify settings.json Integrity

After all modifications, verify settings.json is valid JSON and contains the expected keys:

SETTINGS_FILE="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json"

if jq empty "$SETTINGS_FILE" 2>/dev/null; then
  echo "settings.json: valid JSON"
else
  echo "ERROR: settings.json is invalid JSON! Restoring from backup..."
  exit 1
fi

if jq -e '.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS' "$SETTINGS_FILE" > /dev/null 2>&1; then
  echo "Agent teams: ENABLED"
else
  echo "WARNING: Agent teams env var not found in settings.json"
fi

echo ""
echo "Final settings.json:"
jq '.' "$SETTINGS_FILE"

If User Chooses NO:

Skip this step. Agent teams will remain disabled. User can enable later by adding to ~/.claude/settings.json:

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

Or by running /oh-my-claudecode:omc-setup --force and choosing to enable teams.

Save Progress

CONFIG_TYPE=$(jq -r '.configType // "unknown"' ".omc/state/setup-state.json" 2>/dev/null || echo "unknown")
bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" save 6 "$CONFIG_TYPE"

Phase 4: Completion

Detect Upgrade from 2.x

Check if user has existing 2.x configuration:

ls "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/commands/ralph-loop.md 2>/dev/null || ls "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/commands/ultrawork.md 2>/dev/null

If found, this is an upgrade from 2.x. Set IS_UPGRADE=true.

Show Welcome Message

For New Users (IS_UPGRADE is not true):

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" |
| plan | Planning interview | "plan the new endpoints" |
| team | Coordinated agents | "/team 3:executor fix errors" |

**ralph includes ultrawork:** When you activate ralph mode, it automatically includes ultrawork's parallel execution. No need to combine keywords.

TEAMS:
Spawn coordinated agents with shared task lists and real-time messaging:
- /oh-my-claudecode:team 3:executor "fix all TypeScript errors"
- /oh-my-claudecode:team 5:debugger "fix build errors in src/"
Teams use Claude Code's implicit agent team (spawn teammates directly with distinct `name` values; no TeamCreate/TeamDelete in Claude Code 2.1.178+).

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.

OMC CLI HELPERS (if installed):
- omc hud         - Render the current HUD statusline
- omc teleport    - Create an isolated git worktree
- omc team status - Inspect a running team job
- Session summaries are written to `.omc/sessions/*.json`

That's it! Just use Claude Code normally.

For Users Upgrading from 2.x (IS_UPGRADE is true):

OMC Setup Complete! (Upgraded from 2.x)

GOOD NEWS: Your existing commands still work!
- /ralph, /ultrawork, /omc-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 /omc-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" |
| omc-plan | /omc-plan | "plan the endpoints" |
| team | (new!) | "/team 3:executor fix errors" |

TEAMS (NEW!):
Spawn coordinated agents with shared task lists and real-time messaging:
- /oh-my-claudecode:team 3:executor "fix all TypeScript errors"
- Uses Claude Code's implicit agent team (spawn teammates directly with distinct `name` values; no TeamCreate/TeamDelete in Claude Code 2.1.178+)

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

OMC CLI HELPERS (if installed):
- omc hud         - Render the current HUD statusline
- omc teleport    - Create an isolated git worktree
- omc team status - Inspect a running team job
- Session summaries are written to `.omc/sessions/*.json`

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

Optional Rule Templates

OMC includes rule templates you can copy to your project's .claude/rules/ directory for automatic context injection:

Copy with:

mkdir -p .claude/rules
cp "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/templates/rules/"*.md .claude/rules/

See templates/rules/README.md for details.

Ask About Starring Repository

First, check if gh CLI is available and authenticated:

gh auth status &>/dev/null

If gh is available and authenticated:

Before prompting, check if the repository is already starred:

gh api user/starred/Yeachan-Heo/oh-my-claudecode &>/dev/null

If already starred (exit code 0):

• Skip the prompt entirely
• Continue to completion silently

If NOT starred (exit code non-zero):

Use AskUserQuestion:

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 ""

Mark Completion

Get the current OMC version and mark setup complete:

# Get current OMC version from CLAUDE.md
OMC_VERSION=""
if [ -f ".claude/CLAUDE.md" ]; then
  OMC_VERSION=$(grep -m1 'OMC:VERSION:' .claude/CLAUDE.md 2>/dev/null | sed -E 's/.*OMC:VERSION:([^ ]+).*/\1/' || true)
elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md" ]; then
  OMC_VERSION=$(grep -m1 'OMC:VERSION:' "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/CLAUDE.md" 2>/dev/null | sed -E 's/.*OMC:VERSION:([^ ]+).*/\1/' || true)
fi
if [ -z "$OMC_VERSION" ]; then
  OMC_VERSION=$(omc --version 2>/dev/null | head -1 || true)
fi
if [ -z "$OMC_VERSION" ]; then
  OMC_VERSION="unknown"
fi

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" complete "$OMC_VERSION"