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 COPILOT_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-copilot
• npm users should land here after npm i -g oh-my-copilot@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-copilot

USAGE:
  /oh-my-copilot:omc-setup           Run initial setup wizard (or update if already configured)
  /oh-my-copilot:omc-setup --local   Configure local project (.claude/CLAUDE.md)
  /oh-my-copilot:omc-setup --global  Configure global settings (~/.claude/CLAUDE.md)
  /oh-my-copilot:omc-setup --force   Force full setup wizard even if already configured
  /oh-my-copilot: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
    - Clears retired setup values (5.0.0 removed defaultExecutionMode) and points MCP registration at Claude Code's native config
    - Configures team mode defaults (agent count, type, model)
    - If already configured, offers quick update option

  Local Configuration (--local)
    - Invokes the plugin-local coordinator through `scripts/setup-claude-md.mjs`; the script validates the coordinator response and its exit status before any post-install work
    - Reports coordinator-created byte-identical backups only for files that required mutation
    - Project-specific settings
    - Use this to update project config after OMC upgrades

  Global Configuration (--global)
    - Invokes the plugin-local coordinator through `scripts/setup-claude-md.mjs`; the script validates the coordinator response and its exit status before any post-install work
    - Reports coordinator-created byte-identical backups only for changed global files
    - 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
    - Preserves same-named legacy hook files unless their exact historical contents are independently verified
    - 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-copilot:omc-setup           # First time setup (or update CLAUDE.md if configured)
  /oh-my-copilot:omc-setup --local   # Update this project
  /oh-my-copilot:omc-setup --global  # Update all projects
  /oh-my-copilot:omc-setup --force   # Re-run full setup wizard

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