---
name: omc-setup
description: 按照规范的 setup 流程为 plugin、npm 和本地开发安装或刷新 oh-my-claudecode
level: 2
---

# OMC Setup

这是你**唯一需要学会的命令**。运行它之后，其余一切都是自动完成的。

**调用此技能时，请立即执行下面的工作流。不要仅仅把这些说明重新表述或总结给用户。**

注意：本指南中的所有 `~/.claude/...` 路径在设置了环境变量 `CLAUDE_CONFIG_DIR` 时，都会遵循该变量。

## 最佳适用场景

当用户希望**安装、刷新或修复 OMC 本身**时，选择此 setup 流程。

- Marketplace/plugin 安装用户在执行 `/plugin install oh-my-claudecode` 后应进入这里
- npm 用户在执行 `npm i -g oh-my-claude-sisyphus@latest` 后应进入这里
- 本地开发和 worktree 用户在更新已检出的仓库并重新运行 setup 后应进入这里

## Flag 解析

检查用户调用中是否包含 flags：
- `--help` → 显示帮助文本（见下方）并停止
- `--local` → 仅执行 Phase 1（target=local），然后停止
- `--global` → 仅执行 Phase 1（target=global），然后停止
- `--force` → 跳过预检查，执行完整 setup（Phase 1 → 2 → 3 → 4）
- 无 flags → 先执行预检查，如有需要再执行完整 setup

## 帮助文本

当用户使用 `--help` 运行时，显示以下内容并停止：

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

## Setup 前检查：是否已配置？

**关键**：在执行任何其他操作之前，先检查 setup 是否已经完成。这样可以避免用户在每次更新后都必须重新运行完整的 setup 向导。

```bash
# Check if setup was already completed
CONFIG_FILE="$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
```

### 如果已经配置（且没有 `--force` flag）

如果 `ALREADY_CONFIGURED` 为 true，且用户**没有**传入 `--force`、`--local` 或 `--global` flags：

使用 AskUserQuestion 提示：

**问题：** "OMC is already configured. What would you like to do?"

**选项：**
1. **Update CLAUDE.md only** - 下载最新的 `CLAUDE.md`，但不重新运行完整 setup
2. **Run full setup again** - 重新走一遍完整的 setup 向导
3. **Cancel** - 退出且不做任何更改

**如果用户选择 "Update CLAUDE.md only"：**
- 检测是存在本地配置 `(.claude/CLAUDE.md)` 还是全局配置 `(~/.claude/CLAUDE.md)`
- 如果存在本地配置，运行：`bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-claude-md.sh" local`
- 如果只存在全局配置，运行：`bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-claude-md.sh" global`
- 跳过所有其他步骤
- 报告成功并退出

**如果用户选择 "Run full setup again"：**
- 继续执行下面的 Resume Detection

**如果用户选择 "Cancel"：**
- 退出且不做任何更改

### Force Flag 覆盖

如果用户传入 `--force` flag，跳过此检查并直接进入 setup。

## Resume Detection

在开始任何 phase 之前，检查是否存在已有状态：

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

如果存在状态（输出不是 `"fresh"`），使用 AskUserQuestion 提示：

**问题：** "Found a previous setup session. Would you like to resume or start fresh?"

**选项：**
1. **Resume from step $LAST_STEP** - 从你上次停止的地方继续
2. **Start fresh** - 从头开始（会清除保存的状态）

如果用户选择 "Start fresh"：
```bash
bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup-progress.sh" clear
```

## Phase 执行

### 对于 `--local` 或 `--global` flags：
读取 `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/01-install-claude-md.md` 并遵循其中的说明。
（该 phase 文件会处理 flag 模式下的提前退出。）

### 对于完整 setup（默认或 `--force`）：
按顺序执行各个 phase。对于每个 phase，读取对应文件并遵循其中的说明：

1. **Phase 1 - Install CLAUDE.md**：读取 `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/01-install-claude-md.md` 并遵循其中的说明。

2. **Phase 2 - Environment Configuration**：读取 `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/02-configure.md` 并遵循其中的说明。Phase 2 必须将 HUD/statusLine setup 委托给 `hud` skill；不要在这里内联生成或修补 `statusLine` 路径。

3. **Phase 3 - Integration Setup**：读取 `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/03-integrations.md` 并遵循其中的说明。

4. **Phase 4 - Completion**：读取 `${CLAUDE_PLUGIN_ROOT}/skills/omc-setup/phases/04-welcome.md` 并遵循其中的说明。

## 优雅处理中断

**重要**：此 setup 过程会在每个 phase 之后通过 `${CLAUDE_PLUGIN_ROOT}/scripts/setup-progress.sh` 保存进度。如果被中断（Ctrl+C 或连接丢失），setup 可以从中断处继续恢复。

## 保持最新

在安装 oh-my-claudecode 更新之后（通过 npm 或 plugin update）：

**自动方式**：只需运行 `/oh-my-claudecode:omc-setup`，它会检测你已经完成配置，并提供一个快速的 "Update CLAUDE.md only" 选项，从而跳过完整向导。

**手动选项**：
- `/oh-my-claudecode:omc-setup --local` 仅更新项目配置
- `/oh-my-claudecode:omc-setup --global` 仅更新全局配置
- `/oh-my-claudecode:omc-setup --force` 重新运行完整向导（重新配置偏好）

这样可以确保你拥有最新的功能和 agent 配置，而无需重复完整 setup 所带来的 token 成本。