phases/01-install-claude-md.md
# 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 the user's choice.
## Check the Global Opt-Out Before Asking About Install Style
Only when `CONFIG_TARGET=global`, run this probe before any overwrite/preserve question. It checks the same `.omc-config.json` used by the installer and respects `CLAUDE_CONFIG_DIR`, including `~`, `~/...`, and `~\...` values:
```bash
node -e "
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
let configDir = (process.env.CLAUDE_CONFIG_DIR || '').trim();
if (configDir === '') configDir = path.join(os.homedir(), '.claude');
if (configDir === '~') configDir = os.homedir();
else if (configDir.startsWith('~/') || configDir.startsWith('~' + String.fromCharCode(92))) {
configDir = path.join(os.homedir(), configDir.slice(2));
}
try {
const config = JSON.parse(fs.readFileSync(path.join(configDir, '.omc-config.json'), 'utf8'));
const disabled = Boolean(config && typeof config === 'object' && config.claudeMdEnabled === false);
console.log(disabled ? 'disabled' : 'enabled');
} catch {
console.log('enabled');
}
"
```
If the probe prints `disabled`, do not ask the overwrite/preserve question; set `GLOBAL_INSTALL_STYLE=overwrite` and continue through the coordinator so it can report the skip. If it prints `enabled`, continue below. If the probe fails or prints neither status, stop before asking or running setup; do not assume management is enabled.
If `CONFIG_TARGET=global`, the probe printed `enabled`, 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`.
## Install CLAUDE.md Through the Plugin-Local Coordinator
**MANDATORY**: Always run this command. Do NOT skip. Do NOT use the Write tool. The script is the sole plugin-cache resolver and invokes the selected plugin root's `bridge/claude-md-coordinator.cjs` with one versioned JSON request. It fails closed when required plugin assets, the canonical-source handshake, coordinator response validation, or coordinator exit/`ok` agreement fails.
```bash
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 coordinator exclusively performs all `CLAUDE.md`, `CLAUDE-omc.md`, managed-import, orphan-cleanup, backup, and rollback mutations. Do **not** hand-write, summarize, partially reconstruct, download, or repair either configuration file. It reports only the exact coordinator-created backup, failure, and rollback paths.
If the coordinator output contains the `Skipped CLAUDE.md (claudeMdEnabled is false ...)` note, the user opted out of global CLAUDE.md management in `.omc-config.json`: skip marker verification and report the skip as success. Otherwise, after a successful local or global-overwrite install, verify the target file contains both markers. In global preserve mode, verify `CLAUDE-omc.md` contains both markers and the base `CLAUDE.md` contains exactly one managed import block. Stop and report a coordinator failure; never attempt a shell, downloaded-source, or fallback mutation.
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.
**Note**: Setup never downloads or merges CLAUDE.md in the shell. It uses only the handshake-verified canonical source bundled with the complete active plugin root.
**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 by the active plugin's coordinator at ./.claude/CLAUDE.md
- Git excludes: Added local `.omc/*` ignore rules to `.git/info/exclude` (keeps `.omc/skills/` trackable for committed project skills)
- Backup: Coordinator reported a byte-identical backup only when the previous target required mutation
- 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`:
If the coordinator reported the `claudeMdEnabled` skip, report `CLAUDE.md: Skipped (claudeMdEnabled is false; existing global files were left untouched)` instead of claiming an update, and omit the Companion line. Otherwise, use the report below.
```
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: Coordinator reported byte-identical backups only for global files that required mutation
- 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
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
bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" clear
```
Do not continue to Phase 2 or other phases.
phases/02-configure.md
# Phase 2: Environment Configuration
**Skip condition**: If resuming and `lastCompletedStep >= 4`, skip Steps 2.0–2.3 and begin at Step 2.4 so retired setup values are always cleared before the phase exits.
## Resume Boundary
Capture the original progress marker once when Phase 2 starts. A resumed run that enters at Step 2.4 must not repeat the completed Steps 2.5/2.6 prompts or overwrite a higher progress marker:
```bash
if ! command -v jq >/dev/null 2>&1; then
echo "ERROR: jq is required to resume setup safely. Existing setup state was not modified."
exit 1
fi
if ! RESUME_LAST_COMPLETED_STEP=$(jq -r '.lastCompletedStep // 0' ".omc/state/setup-state.json" 2>/dev/null); then
echo "ERROR: Setup state is invalid JSON. Existing setup state was not modified."
exit 1
fi
if [ "$RESUME_LAST_COMPLETED_STEP" -ge 4 ] 2>/dev/null; then
RESUMED_PHASE_TWO_BOUNDARY="true"
else
RESUMED_PHASE_TWO_BOUNDARY="false"
fi
```
## Step 2.0: Check Ralph Runtime Prerequisites
Ralph is an agent-driven persistence loop with no external language dependency. Its only hard prerequisites are the Node runtime that already runs OMC's hooks and a writable config directory for `.omc/state/` state files. Verify both without blocking the rest of setup:
```bash
node --version || echo "ERROR: Node is required for OMC hooks and Ralph state persistence."
mkdir -p "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" 2>/dev/null
touch "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.omc-write-probe" 2>/dev/null && rm -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.omc-write-probe" \
|| echo "WARNING: Config dir is not writable; Ralph state persistence will fail until it is."
```
## 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:
```bash
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.
```bash
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:
```bash
# Detect installed version (cross-platform)
node -e "
const p=require('path'),f=require('fs'),h=require('os').homedir();
const raw=process.env.CLAUDE_CONFIG_DIR?.trim();
const d=raw==null||raw===''? p.join(h,'.claude'):raw==='~'?h:raw.startsWith('~/')||raw.startsWith('~\\\\')?p.join(h,raw.slice(2)):raw;
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: Clear Retired Setup Values
The `ultrawork` workflow was removed in 5.0.0 and the `defaultExecutionMode` config key is no longer read by any runtime surface. Upgrades from 4.x may still carry a dead persisted value in `.omc-config.json`. Clear it so the config matches the current contract:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
CONFIG_FILE="$CONFIG_DIR/.omc-config.json"
if [ -f "$CONFIG_FILE" ] && grep -q '"defaultExecutionMode"' "$CONFIG_FILE" 2>/dev/null; then
if ! command -v jq >/dev/null 2>&1; then
echo "WARNING: jq is required to clear the retired defaultExecutionMode key from $CONFIG_FILE."
echo "The stale value is harmless (no runtime reads it), but install jq and rerun setup to clean it."
else
TEMP_FILE=$(mktemp "${CONFIG_FILE}.tmp.XXXXXX")
trap 'rm -f "$TEMP_FILE"' EXIT
if jq 'del(.defaultExecutionMode)' "$CONFIG_FILE" > "$TEMP_FILE" \
&& mv "$TEMP_FILE" "$CONFIG_FILE"; then
echo "Cleared retired defaultExecutionMode key (ultrawork was removed in 5.0.0)"
else
echo "WARNING: Failed to clear retired defaultExecutionMode. Existing config was not modified."
rm -f "$TEMP_FILE"
fi
trap - EXIT
fi
fi
```
**Note:** Never write a new `defaultExecutionMode` value. Generic keywords no longer route through a configured execution mode; invoke `/oh-my-claudecode:execute` or `/oh-my-claudecode:team` directly instead.
**Resume-only boundary:** If `RESUMED_PHASE_TWO_BOUNDARY` is `true`, stop Phase 2 after this cleanup. Do not execute Steps 2.5 or 2.6, do not prompt for task-tool or team settings again, and do not save a new progress value. Return to the setup orchestrator with the original `RESUME_LAST_COMPLETED_STEP` unchanged.
## 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:
```bash
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**:
```bash
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:
```bash
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:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
CONFIG_FILE="$CONFIG_DIR/.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" \
&& mv "$TEMP_FILE" "$CONFIG_FILE"; then
:
else
echo "ERROR: Failed to update $CONFIG_FILE. Existing config was not modified."
rm -f "$TEMP_FILE"
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
```bash
CONFIG_TYPE=$(jq -r '.configType // "unknown"' ".omc/state/setup-state.json" 2>/dev/null || echo "unknown")
if [ "${RESUMED_PHASE_TWO_BOUNDARY:-false}" != "true" ]; then
bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh" save 4 "$CONFIG_TYPE"
else
echo "Resumed Phase 2: preserving lastCompletedStep=$RESUME_LAST_COMPLETED_STEP"
fi
```
phases/03-integrations.md
# Phase 3: Integration Setup
**Skip condition**: If resuming and `lastCompletedStep >= 6`, skip this entire phase.
## Step 3.1: Verify Plugin Installation
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
grep -q "oh-my-claudecode" "$CONFIG_DIR/settings.json" && echo "Plugin verified" || echo "Plugin NOT found - run: claude /install-plugin oh-my-claudecode"
```
## Step 3.2: MCP Server Configuration (Pointer Only)
MCP servers extend Claude Code with additional tools (web search, GitHub, etc.). OMC no longer ships an MCP setup skill; servers are registered through Claude Code's native MCP surfaces.
If the user asks about MCP servers, point them at the native registration path:
- Claude Code: `claude mcp add <name> ...` (see `claude mcp --help`), or the native MCP config selected by `CLAUDE_MCP_CONFIG_PATH` (by default, `$CLAUDE_CONFIG_DIR/.claude.json` when `CLAUDE_CONFIG_DIR` names a profile other than `~/.claude`, otherwise `~/.claude.json`)
- OMC keeps its own bundled MCP server (`bridge/mcp-server.cjs`) registered via `.mcp.json`; it requires no user action
- Company-context guidance, if used, is documented in `docs/company-context-interface.md`
Do **not** try to invoke an MCP setup skill — `mcp-setup` was removed in 5.0.0 and has no replacement skill; the native surfaces above are the whole story.
## 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:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
SETTINGS_FILE="$CONFIG_DIR/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:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
SETTINGS_FILE="$CONFIG_DIR/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" \
&& mv "$TEMP_FILE" "$SETTINGS_FILE"; then
:
else
echo "ERROR: Failed to update $SETTINGS_FILE. Existing settings were not modified."
rm -f "$TEMP_FILE"
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:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
SETTINGS_FILE="$CONFIG_DIR/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" \
&& mv "$TEMP_FILE" "$SETTINGS_FILE"; then
:
else
echo "ERROR: Failed to update $SETTINGS_FILE. Existing settings were not modified."
rm -f "$TEMP_FILE"
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](https://antigravity.google))
Store the team configuration in the active Claude config directory's `.omc-config.json`:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
CONFIG_FILE="$CONFIG_DIR/.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" \
&& mv "$TEMP_FILE" "$CONFIG_FILE"; then
:
else
echo "ERROR: Failed to update $CONFIG_FILE. Existing config was not modified."
rm -f "$TEMP_FILE"
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:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
SETTINGS_FILE="$CONFIG_DIR/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`:
```json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
```
Or by running `/oh-my-claudecode:omc-setup --force` and choosing to enable teams.
## Save Progress
```bash
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"
```
phases/04-welcome.md
# Phase 4: Completion
## Detect Upgrade from 2.x
Check if user has existing 2.x configuration:
```bash
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
ls "$CONFIG_DIR/commands/ralph-loop.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
MAGIC KEYWORDS (optional power-user shortcuts):
Just include these words naturally in your request:
| Keyword | Effect | Example |
|---------|--------|---------|
| autopilot | Autonomous execution | "autopilot build me a todo app" |
| ralph | Persistence mode | "ralph: fix the auth bug" |
| ralplan | Iterative consensus planning | "ralplan this feature" |
| deep interview | Requirements interview | "deep interview me before coding" |
| deslop / anti-slop | Cleanup review | "deslop this module" |
| deep-analyze | Analysis mode | "deep-analyze the flaky test" |
| tdd | TDD mode | "tdd the parser" |
| deepsearch | Codebase search | "deepsearch where config is loaded" |
| ultrathink | Deep reasoning | "ultrathink this design" |
| cancelomc | Stop active OMC modes | "cancelomc" |
CANONICAL WORKFLOWS (Tier-0):
omc-plan -> execute -> omc-review -> verify, invoked as /oh-my-claudecode:omc-plan and /oh-my-claudecode:omc-review.
/deep-interview and /ralplan are independent planning workflows.
/research and /team are internal lanes; /autopilot, /autoresearch, /ralph, /ultragoal stay directly invocable.
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+). Team orchestration is explicit via /team — there is no bare "team" keyword.
MCP SERVERS:
Register extra MCP servers (web search, GitHub, etc.) through Claude Code's native MCP config (`claude mcp add ...` or the path selected by `CLAUDE_MCP_CONFIG_PATH`; by default, `$CLAUDE_CONFIG_DIR/.claude.json` when `CLAUDE_CONFIG_DIR` names a profile other than `~/.claude`, otherwise `~/.claude.json`). OMC's bundled MCP server is already registered via the plugin's .mcp.json.
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.
```
### Retired in 5.0.0 (all users)
The following commands and keywords were removed in 5.0.0 and are not aliased:
/ultrawork, /ultraqa, /ultrapilot, /swarm, /pipeline, /merge-readiness,
/deep-dive, /sciomc, /ccg, /omc-teams, /setup, /mcp-setup, /omc-reference,
/learner, /writer-memory, /local-build-reminder.
Use the replacement instead — see the migration table in docs/MIGRATION.md
(commonly /execute for ultrawork, /verify for ultraqa, /team for omc-teams,
/omc-setup for setup, and Claude Code's native MCP config for mcp-setup;
/wiki for omc-reference).
### For Users Upgrading from 2.x (IS_UPGRADE is true):
```
OMC Setup Complete! (Upgraded from 2.x)
IMPORTANT: Some legacy 2.x and 3.x commands were retired in 5.0.0 and are
not aliased. Use the replacement workflows listed in the migration table.
WHAT'S NEW in 3.0:
You no longer NEED those commands. Everything is automatic now:
- Just say "autopilot build me ..." instead of /autopilot
- Just say "ralph: <task>" instead of /ralph
- Just say "cancelomc" instead of /cancel
MAGIC KEYWORDS (power-user shortcuts):
| Keyword | Same as old... | Example |
|---------|----------------|---------|
| autopilot | /autopilot | "autopilot build me a todo app" |
| ralph | /ralph | "ralph: fix the bug" |
| ralplan | /ralplan | "ralplan this feature" |
| deep interview | /deep-interview | "deep interview me before coding" |
| cancelomc | /cancel | "cancelomc" |
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 configuration is preserved; retired commands are not recreated.
```
## Optional Rule Templates
OMC includes rule templates you can copy to your project's `.claude/rules/` directory for automatic context injection:
| Template | Purpose |
|----------|---------|
| `coding-style.md` | Code style, immutability, file organization |
| `testing.md` | TDD workflow, 80% coverage target |
| `security.md` | Secret management, input validation |
| `performance.md` | Model selection, context management |
| `git-workflow.md` | Commit conventions, PR workflow |
| `karpathy-guidelines.md` | Coding discipline -- think before coding, simplicity, surgical changes |
Copy with:
```bash
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:
```bash
gh auth status &>/dev/null
```
### If gh is available and authenticated:
**Before prompting, check if the repository is already starred:**
```bash
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!":
```bash
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:
```bash
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:
```bash
# Get current OMC version from CLAUDE.md
OMC_VERSION=""
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
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 "$CONFIG_DIR/CLAUDE.md" ]; then
OMC_VERSION=$(grep -m1 'OMC:VERSION:' "$CONFIG_DIR/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"
```
SKILL.md
---
name: omc-setup
description: Install or refresh oh-my-claudecode for plugin, npm, and local-dev setups from the canonical setup flow
level: 2
---
# 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
- 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.sh`; the shell 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.sh`; the shell 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-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
```
## Setup Invocation
Do not independently scan plugin cache directories or select a plugin root in this skill. Invoke the setup script from the plugin root supplied by the running plugin environment:
```bash
bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" <local|global> [overwrite|preserve]
```
The script is the sole cache resolver. It accepts only complete plugin roots (canonical `docs/CLAUDE.md`, coordinator artifact, and `wiki` skill), chooses a strict full-SemVer cache version, verifies the compiled-source handshake, and fails closed on coordinator protocol or status disagreement. Do not download configuration or mutate `CLAUDE.md` outside that coordinator.
## 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.
```bash
# Check if setup was already completed
CONFIG_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
case "$CONFIG_DIR" in
"~") CONFIG_DIR="$HOME" ;;
"~/"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~/}" ;;
"~\\"*) CONFIG_DIR="$HOME/${CONFIG_DIR#\~\\}" ;;
esac
CONFIG_FILE="$CONFIG_DIR/.omc-config.json"
if [ -f "$CONFIG_FILE" ]; then
if ! command -v jq >/dev/null 2>&1; then
echo "ERROR: jq is required to inspect existing OMC setup state. Existing config was not modified."
exit 1
fi
if ! SETUP_COMPLETED=$(jq -r '.setupCompleted // empty' "$CONFIG_FILE" 2>/dev/null) \
|| ! SETUP_VERSION=$(jq -r '.setupVersion // empty' "$CONFIG_FILE" 2>/dev/null); then
echo "ERROR: Existing OMC config is invalid JSON. Existing config was not modified."
exit 1
fi
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 and clear retired setup values** - Install the active plugin's canonical CLAUDE.md and run Phase 2 Step 2.4 without re-running the full setup
2. **Run full setup again** - Go through the complete setup wizard
3. **Cancel** - Exit without changes
**If user chooses "Update CLAUDE.md and clear retired setup values":**
- 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`
- Run Phase 2 Step 2.4 to clear the retired `defaultExecutionMode` key
- Skip all other steps after the cleanup
- 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
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
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 and clear retired setup values" option that skips the rest of the wizard.
The quick update path must still perform Phase 2 Step 2.4 so upgrades remove the retired `defaultExecutionMode` value; it must not write any replacement execution-mode setting.
**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.