omc-setup

OMC 安装配置

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

当此技能被调用时，立即执行下面的工作流。不要只是把这些说明复述或总结给用户。

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

最佳适用场景

当用户想要安装、刷新或修复 OMC 本身时，选择此安装配置流程。

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

标志解析

检查用户调用中是否包含以下标志：

• --help → 显示帮助文本（见下文）并停止
• --local → 仅执行阶段 1（target=local），然后停止
• --global → 仅执行阶段 1（target=global），然后停止
• --force → 跳过安装前检查，运行完整安装配置（阶段 1 → 2 → 3 → 4）
• 无标志 → 运行安装前检查，然后按需运行完整安装配置

帮助文本

当用户带 --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
    - 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

安装配置调用

不要在此技能中独立扫描插件缓存目录或自行选择插件根目录。从正在运行的插件环境所提供的插件根目录调用安装配置脚本：

bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" <local|global> [overwrite|preserve]

该脚本是唯一的缓存解析器。它只接受完整的插件根目录（包含规范的 docs/CLAUDE.md、协调器产物和 wiki 技能），选择严格的完整 SemVer 缓存版本，验证编译源码握手，并在协调器协议或状态不一致时按失败关闭处理。不要在该协调器之外下载配置或改动 CLAUDE.md。

安装前检查：是否已配置？

关键：在做任何其他事情之前，检查安装配置是否已经完成。这可避免用户在每次更新后都必须重新运行完整的安装配置向导。

# 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

如果已配置（且没有 --force 标志）

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

使用 AskUserQuestion 提示：

问题： "OMC 已经配置完成。你想做什么？"

选项：

1. 更新 CLAUDE.md 并清除已弃用的安装配置值 - 安装当前活动插件的规范 CLAUDE.md，并运行阶段 2 步骤 2.4，不重新运行完整安装配置
2. 再次运行完整安装配置 - 走完整的安装配置向导
3. 取消 - 不做任何更改并退出

如果用户选择"更新 CLAUDE.md 并清除已弃用的安装配置值"：

• 检测本地（.claude/CLAUDE.md）或全局（~/.claude/CLAUDE.md）配置是否存在
• 如果本地存在，运行：bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" local
• 如果只有全局存在，运行：bash "${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-claude-md.sh" global
• 运行阶段 2 步骤 2.4 以清除已弃用的 defaultExecutionMode 键
• 清理后跳过所有其他步骤
• 报告成功并退出

如果用户选择"再次运行完整安装配置"：

• 继续执行下面的恢复检测

如果用户选择"取消"：

• 不做任何更改并退出

Force 标志覆盖

如果用户传入 --force 标志，跳过此检查并直接进入安装配置。

恢复检测

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

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

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

问题： "发现了之前的安装配置会话。你想恢复还是重新开始？"

选项：

1. 从步骤 $LAST_STEP 恢复 - 从你中断的地方继续
2. 重新开始 - 从头开始（清除已保存的状态）

如果用户选择"重新开始"：

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

阶段执行

对于 --local 或 --global 标志：

读取文件 ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/01-install-claude-md.md 并遵循其说明。 （该阶段文件处理标志模式下的提前退出。）

完整安装（默认或 --force）：

按顺序执行各阶段。对于每个阶段，读取相应文件并遵循其说明：

1. 阶段 1 - 安装 CLAUDE.md：读取 ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/01-install-claude-md.md 并遵循其说明。

2. 阶段 2 - 环境配置：读取 ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/02-configure.md 并遵循其说明。阶段 2 必须将 HUD/statusLine 的设置委托给 hud skill；不要在此处内联生成或修补 statusLine 路径。

3. 阶段 3 - 集成设置：读取 ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/03-integrations.md 并遵循其说明。

4. 阶段 4 - 完成：读取 ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/omc-setup/phases/04-welcome.md 并遵循其说明。

优雅中断处理

重要：此安装过程会在每个阶段后通过 ${OMC_SETUP_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/setup-progress.sh 保存进度。如果中断（Ctrl+C 或连接丢失），安装可以从上次中断处继续。

保持更新

在安装 oh-my-claudecode 更新后（通过 npm 或插件更新）：

自动：只需运行 /oh-my-claudecode:omc-setup - 它会检测到你已配置过，并提供快速的"更新 CLAUDE.md 并清除已弃用的安装值"选项，跳过向导的其余部分。

快速更新路径仍必须执行阶段 2 步骤 2.4，以便升级时移除已弃用的 defaultExecutionMode 值；它不得写入任何替代的执行模式设置。

手动选项：

• /oh-my-claudecode:omc-setup --local 仅更新项目配置
• /oh-my-claudecode:omc-setup --global 仅更新全局配置
• /oh-my-claudecode:omc-setup --force 重新运行完整向导（重新配置偏好设置）

这确保你能获得最新的功能和 Agent 配置，而无需付出重复完整安装的 token 成本。