oh-my-claudecode 本地开发版安装指南：以 Marketplace 与 `--plugin-dir` 两种方式将仓库源码接入 Claude Code

oh-my-claudecode 本地开发版安装指南以 Marketplace 与--plugin-dir两种方式将仓库源码接入 Claude Code【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode本文是 oh-my-claudecode 面向本地开发检出local development checkout与 git worktree 场景的安装与迭代实战指南。它解决一个具体问题当你在本地修改 agents、skills、commands 甚至 TypeScript 源码时如何让 Claude Code 加载的是当前仓库状态而非发布版插件从而保证「你改的代码 Claude Code 实际运行的插件」。读完本文你将掌握claude plugin marketplace系列命令的完整用法、plugin.json清单结构、以及无缓存热迭代的--plugin-dir/--plugin-dir-mode开发流并理解两者在文件落盘位置、缓存行为与优先级规则上的本质差异。本文适用人群先确认你的安装场景oh-my-claudecode 的插件安装并非「一招通吃」文档首先按使用场景做了分流避免误用错误的安装路径场景推荐路径说明Marketplace / 普通插件用户README 快速开始流程直接消费已发布插件npm 用户npm i -g oh-my-claude-sisyphuslatestnpm 全局安装会同时暴露oh-my-claudecode与omc两个命令别名本地开发 / worktree 用户本文保证已安装插件与你正在编辑的分支/worktree 一致两个命令别名的定义可在 package.json 的bin字段中查到实证oh-my-claudecode: bin/oh-my-claudecode.js与omc: bin/oh-my-claudecode.js指向同一个入口文件而omc-cli则映射到bridge/cli.cjs。这意味着无论你用哪个别名行为完全一致——这正是后续所有命令可以互换使用的前提。快速安装把本地目录注册为 Marketplace对于本地开发检出最直接的接入方式是让 Claude Code 将仓库根目录本身当作一个 marketplace 插件源再从中安装插件# 1. 将本地目录添加为 marketplace claude plugin marketplace add /path/to/oh-my-claudecode # 2. 从该本地 marketplace 安装插件 claude plugin install oh-my-claudecodeoh-my-claudecode # 3. 在 Claude Code 中重跑 setup使 CLAUDE.md / skills 与此检出保持一致 /setup # 4. 重启 Claude Code 以加载插件要点说明plugin install的目标采用插件名市场名的双段写法其中后的oh-my-claudecode指代的是第 1 步注册的 marketplace 名称而非版本号。/setup是 Claude Code 会话内命令作用是把当前检出的 CLAUDE.md、skills、hooks 等内容同步到用户配置目录让提示词与技能文件版本跟随插件。第 4 步的会话重启必不可少——Claude Code 的插件加载发生在会话启动阶段。命令参考表marketplace 全生命周期操作命令列出已配置的 marketplaceclaude plugin marketplace list更新 marketplace重新读取源claude plugin marketplace update oh-my-claudecode更新已安装插件claude plugin update oh-my-claudecodeoh-my-claudecode列出已安装插件claude plugin list卸载插件claude plugin uninstall oh-my-claudecodeoh-my-claudecode移除 marketplaceclaude plugin marketplace remove oh-my-claudecode插件结构plugin.json清单的真实形态任何可被 Claude Code 识别的插件都要求仓库包含清单文件。文档给出一份结构示意清单{ name: oh-my-claudecode, version: 3.4.0, description: Multi-agent orchestration system for Claude Code, hooks: { PreToolUse: [scripts/pre-tool-enforcer.mjs], PostToolUse: [scripts/post-tool-verifier.mjs], SessionStart: [scripts/session-start.mjs] }, agents: [agents/*.md], commands: [commands/**/*.md], skills: [skills/*.md] }需要强调的是上例中的version: 3.4.0仅为结构示意。本仓库真实的清单位于.claude-plugin/plugin.json当前版本号与 package.json 保持一致5.0.2且字段组织更为细粒度skills以数组形式逐个声明 28 个技能目录./skills/ai-slop-cleaner/、./skills/ask/、./skills/autopilot/、./skills/team/、./skills/visual-verdict/等mcpServers指向./.mcp.json声明随插件分发的 MCP Server 配置commands指向./commands/目录随插件装载全部斜杠命令附带author、repository、license: MIT、keywords等元数据便于 marketplace 索引与展示。清单中引用的三个 hooks 脚本在仓库中都能找到对应实体scripts/pre-tool-enforcer.mjs、scripts/post-tool-verifier.mjs、scripts/session-start.mjs。hooks、agents/*.md、commands/**/*.md、skills/*.md这些路径模式揭示了 oh-my-claudecode 的资源组织约定一切可被插件装载的用户侧资产都以声明式路径列出Claude Code 插件系统据此将它们映射到~/.claude/plugins/cache/的对应子目录。开发工作流Marketplace 缓存模式的「改代码五连」热重载警告务必先读claude plugin marketplace add 本地目录实际执行的是拷贝/缓存插件内容会被复制到~/.claude/plugins/cache/之下——它不会监视你的检出目录。因此每一次对 agents、skills 或 commands 的修改都需要显式走完下面这套「marketplace update plugin update 重跑 setup」流程# 1. 构建若改动涉及 TypeScript npm run build # 2. 更新 marketplace 缓存 claude plugin marketplace update oh-my-claudecode # 3. 更新已安装插件 claude plugin update oh-my-claudecodeoh-my-claudecode # 4. 在 Claude Code 中重跑 setup使 prompts/skills 与刷新后的插件一致 /setup # 5. 重启 Claude Code 会话这套流程同样适用于从关联 git worktree做改动的情形——worktree 中的编辑与主检出的编辑在流程上没有任何区别。若你追求「无需 marketplace 刷新即可生效」的无缓存开发循环请跳过本小节直接使用下文的--plugin-dir方案。npm run build的真实复杂度可以从 package.json 的 build 脚本一窥它依次执行generate-skill-entitlements、tsc编译、构建 workflow-stage-prompts、skill-bridge、MCP Server、bridge 入口、runtime-cli、team-server 与 CLI 产物并附带compose-docs与generate:prompt-projections。也就是说只要触及 TypeScript 侧逻辑如src/cli/launch.ts的启动器、src/installer/index.ts的安装器插件更新前就必须完整构建一次。与 npm 全局安装的取舍方法命令文件落盘位置插件模式claude plugin install~/.claude/plugins/cache/npm 全局npm install -g~/.claude/agents/、~/.claude/commands/插件模式是推荐首选它把文件隔离在插件缓存内利用 Claude Code 原生插件系统并支持以${CLAUDE_PLUGIN_ROOT}变量进行路径解析。这一变量的真实用途在 docs/REFERENCE.md 的 MCP 配置示例中体现得很清楚——例如 team MCP 服务的args可以写作[${CLAUDE_PLUGIN_ROOT}/bridge/team-mcp.cjs]让 MCP Server 的绝对路径始终跟随当前插件实例而非写死某个安装位置。npm 全局安装则把 agents 与 commands 直接铺进用户级目录文件虽可被多个项目共享但丧失了插件级别的隔离与版本管理。备选方案--plugin-dir无缓存开发流若不想使用 marketplace 系统可直接以--plugin-dir启动 Claude Code让插件直接从你的文件系统加载无缓存export OMC_PLUGIN_ROOT/path/to/oh-my-claudecode claude --plugin-dir /path/to/oh-my-claudecode omc setup --plugin-dir-mode或者使用会自动处理--plugin-dir的 npm CLI shimomc或用完整别名oh-my-claudecodeomc --plugin-dir /path/to/oh-my-claudecode setup --plugin-dir-mode # 等价的长别名写法 oh-my-claudecode --plugin-dir /path/to/oh-my-claudecode setup --plugin-dir-mode与 marketplace 模式的关键差异插件直接从文件系统加载不存在缓存层对 agent/skill 文件的改动在重跑omc setup后即可生效无需marketplace update 步骤——只需重新构建并重跑 setup若直接使用claude而非omc/oh-my-claudecodeshim需要手动导出OMC_PLUGIN_ROOTshim 会自动替你设置。源码视角--plugin-dir与OMC_PLUGIN_ROOT到底做了什么理解这套备选方案的底层机制会让排错事半功倍。相关逻辑散落在三个源码位置启动器捕获插件路径src/cli/launch.ts中的parsePluginDirArg()以非消费式non-consuming方式解析原始 argv——它支持--plugin-dir path与--plugin-dirpath两种写法解析成功后把路径写入OMC_PLUGIN_ROOT环境变量但不把该参数从参数列表中移除因此它仍会原样透传给 Claude Code 自身的插件加载器见 src/cli/launch.ts。路径归一化src/lib/plugin-dir.ts中的resolvePluginDirArg()负责把相对路径转为绝对路径并做了跨平台判断同时识别 POSIX 与 Windows 的绝对路径格式空值会直接抛错。注意文档强调~不会被展开请使用$HOME或绝对路径见 src/lib/plugin-dir.ts。安装器跳过拷贝src/installer/index.ts中pluginDirMode一旦生效shouldInstallLegacyAgents与shouldInstallBundledSkills均会被关闭——因为插件已通过--plugin-dir在运行时提供了 agents/skills无需再向~/.claude/拷贝副本但 HUD、git hooks、CLAUDE.md、.omc-config.json仍然照常安装见 src/installer/index.ts。优先级规则可以总结为三条显式--plugin-dir优先于已有的OMC_PLUGIN_ROOT环境变量不一致时给出告警--plugin-dir只影响当前 Claude 会话必须配合omc setup --plugin-dir-mode才会把 HUD/hooks/CLAUDE.md 安装到对应检出否则~/.claude/会指向过期的插件根目录--no-plugin与--plugin-dir-mode同时出现时--no-plugin胜出。最后一条规则在 src/installer/tests/plugin-dir-mode.test.ts 与 src/installer/tests/plugin-dir-mode-e2e.test.ts 中都有对应断言前者验证pluginDirMode: true时~/.claude/agents、~/.claude/skills不被创建后者以真实install()跑通端到端文件系统形状确认 HUD/CLAUDE.md/settings 被安装而 agents/skills 保持为空。决策矩阵你的开发形态该选哪套组合下表整理自 docs/REFERENCE.md可直接对照选用你的环境启动命令setup 命令预期行为Marketplace 插件推荐omc或claude默认omc setup常规agents/skills 拷贝至~/.claude/本地检出 使用 OMC shimomc --plugin-dir /pathomc setup --plugin-dir-mode开发模式从/path加载不再拷贝本地检出 不用 OMC shimclaude --plugin-dir /pathexport OMC_PLUGIN_ROOT/pathomc setup --plugin-dir-mode开发模式 手动环境变量本地开发 想要内置技能omc --plugin-dir /pathomc setup --no-plugin强制把内置技能装入~/.claude/skills/忽略插件排查指定路径不适用omc doctor --plugin-dir /path诊断结果显示/path的状态故障排查手册插件未加载安装后重启 Claude Code检查claude plugin list确认状态为enabled确认plugin.json存在且是合法 JSON。版本看起来是旧的缓存目录名可能显示旧版本但实际代码来自最新 commit依次执行claude plugin marketplace update后再claude plugin update。使用了--plugin-dir或--plugin-dir-mode验证OMC_PLUGIN_ROOT已设置echo $OMC_PLUGIN_ROOT若直接使用claude --plugin-dir而非omc --plugin-dir需手动导出OMC_PLUGIN_ROOT运行omc doctor --plugin-dir /path/to/oh-my-claudecode或长别名oh-my-claudecode doctor --plugin-dir /path/to/oh-my-claudecode进行诊断。omc doctor是定位安装/插件问题的专用入口其冲突检查子命令同样接受--plugin-dir用于在指定插件目录上下文中做诊断其实现位于 src/cli/commands/doctor-conflicts.ts相关冲突语义可参阅 commands/omc-doctor.md。doctor与doctor conflicts都会在动作执行前把指定路径解析为绝对路径并设定OMC_PLUGIN_ROOT与launch.ts的语义保持一致——这意味着「启动时指向哪套插件、诊断时就查哪套插件」两者永不错位。小结本地开发 oh-my-claudecode 时核心矛盾是版本跟随与迭代速度marketplace 模式适合需要正式版本管理、按 cache 隔离的场景代价是每次改动都要走「update marketplace → update plugin → 重跑 setup」的往返--plugin-dir--plugin-dir-mode则牺牲了市场分发能力换来从检出目录直接加载的无缓存开发闭环。理解OMC_PLUGIN_ROOT、${CLAUDE_PLUGIN_ROOT}、pluginDirMode三个概念各自的读写方与优先级你就掌握了在不同工作形态之间无缝切换的钥匙。若需要更完整的决策依据与参数语义可继续查阅 docs/REFERENCE.md 的 Plugin directory flags 章节。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考