Hamster

Hamster

安装 Hamster。 一个插件。通过托管 MCP 或命令行进行交流。将计划保存在磁盘上，然后按计划交付。

这就是 Hamster 产品：在所有受支持的客户端上提供 Agent Plugins skills；在所有支持 MCP 且支持从 GitHub 或应用市场安装的客户端上提供托管 MCP；此外，还在 Claude Code、GitHub Copilot CLI 和 Grok Build 上提供生成的原生执行工作器。CLI 用于将计划保存在此仓库中。它不是第二种安装方式。

安装

不同客户端的安装方式有所不同。如果你使用多个客户端，请分别为每个客户端安装 Hamster。

Cursor

1. 选择 Customize → Add Marketplace → Import from GitHub。
2. 在 User 范围内粘贴 https://github.com/gethamster/plugin，然后选择 Import。
3. 打开 Personal 选项卡，然后选择 Hamster 旁边的 Add。

在 Enterprise 上，管理员必须允许导入应用市场。Hamster 上架 Cursor 应用市场后，也可以使用 /add-plugin hamster：

/add-plugin hamster

Grok Bot 不是独立的 Hamster 软件包。它使用相同的 Cursor 账号和插件库，因此上述 Cursor 安装方式就是 Grok Bot 的安装方式。不要在 Grok Bot 聊天中运行 /add-plugin。如果 Grok Bot 显示“Complete GitHub auth to sync installed plugins”，请按 Grok Bot 的提示完成 GitHub 身份验证。

Claude Code

/plugin marketplace add gethamster/plugin
/plugin install hamster@hamster-plugins

Codex CLI

codex plugin marketplace add gethamster/plugin
codex plugin add hamster@hamster-plugins

你也可以启动 codex，运行 /plugins，然后安装 hamster@hamster-plugins。

Codex 插件目录

OpenAI 插件目录中的 Hamster 条目供 Codex 和 ChatGPT 使用，它是通过 node scripts/build-codex-bundle.mjs 生成的同一插件压缩包：包括 Codex 清单、.mcp.json 中的托管 MCP 连接器、技能和条目图片。CI 会在每次推送时构建该压缩包，并将其作为工作流产物上传；下载的产物就是要上传到目录的压缩包。

其中有一处不同。压缩包会将 skills/setup/SKILL.md 中的“安装 CLI”部分替换为 codex-directory/install-cli.md：如果缺少 CLI，安装流程会要求你从 CLI 二进制文件 手动安装，而不是运行安装程序，然后照常登录并同步。

Hamster 通过托管 MCP 服务连接到你的工作区。编码技能需要访问你的代码库和 shell。

Antigravity

从克隆的此仓库安装：

agy plugin install ./plugins/hamster

或从 GitHub 安装：

agy plugin install https://github.com/gethamster/plugin/plugins/hamster

两种方式都会安装 plugins/hamster，这是其他所有客户端安装的文件夹。直接使用仓库 URL 也可以，但 agy 会将根目录作为 Gemini CLI 扩展导入，并丢弃 Agent 的模型设置；运行上述命令会原位替换该安装。

如果已安装 Hamster 3.2，请先卸载，再安装 3.4。Antigravity 原位安装会保留 3.4 中已重命名的四个技能目录。

agy plugin uninstall hamster
agy plugin install https://github.com/gethamster/plugin/plugins/hamster

在 Antigravity 应用（2.15 或更高版本）中，通过 Settings → Customizations → Installed MCP Servers 对 hamster_hamster 进行身份验证。插件会自行注册该服务，因此在 mcp_config.json 中手动添加 hamster 会导致每个工具都出现两份。

使用 GitHub Copilot CLI、Gemini CLI、Grok Build、OpenCode 或 Pi？请参阅更多安装选项。

更多安装选项

GitHub Copilot CLI

copilot plugin marketplace add gethamster/plugin
copilot plugin install hamster@hamster-plugins

要登录托管 MCP 服务，请运行 /mcp auth hamster。

Gemini CLI

gemini extensions install https://github.com/gethamster/plugin

要登录托管 MCP 服务，请运行 /mcp auth hamster。

Grok Build

grok plugin install gethamster/plugin --trust

要登录托管 MCP 服务，请打开 /mcps，选择 hamster，然后按 i。

OpenCode

OpenCode 分两步安装技能和托管 MCP 服务。在项目文件夹中运行以下命令：

npx skills add gethamster/plugin --agent opencode
opencode mcp add hamster --url https://tryhamster.com/mcp

在 npx skills add 后添加 --global，即可将技能安装到 ~/.agents/skills/，而不是当前项目中（opencode mcp add --url 需要 OpenCode 1.17.0 或更高版本）。

要登录托管 MCP 服务，请运行 opencode mcp auth hamster。

Pi

pi install npm:@tryhamster/pi

若要跟踪代码仓库而非 npm 版本，请运行 pi install git:github.com/gethamster/plugin。

Pi 软件包仅安装技能。若要连接托管的 MCP 服务，请添加该服务并登录：

pi mcp add hamster --url https://tryhamster.com/mcp
pi mcp login hamster

安装后

1. 交流 — 使用托管 MCP https://tryhamster.com/mcp；若 MCP 工具不可用且 CLI 已登录，则使用 hamster chat。客户端负责 Hamster 登录。
2. 在磁盘上制定计划 — 说“Install Hamster”，或运行 ship。设置技能会在需要时安装 CLI、运行 hamster auth login，并同步计划。
3. 交付 — 执行已保存在磁盘上的简报。会话启动时不会自动运行任何操作。

技能

Claude Code 和 Copilot CLI 会将这些技能列为 /hamster:<skill>。Cursor 和 Grok Build 会将其列为 /<skill>，Pi 则列为 /skill:<skill>。在 OpenCode 中，按名称请求技能；在 OpenCode 2 中，则以 @setup 的形式提及。表格使用 Claude 格式。

技能	角色	描述
/hamster:setup	—	安装 CLI、登录，并将计划同步到此仓库
/hamster:ask-hamster [request]	工作区 Copilot	将当前代码与工作区优先事项、阻碍、蓝图或相关工作联系起来（客户端支持时使用托管 MCP；否则使用 hamster chat）
/hamster:ship [brief]	发布工程师	交付简报：合并基线、并行实施、测试、审查、可二分的提交、PR
/hamster:plan-hamster [brief]	技术负责人 + CEO/工程模式	分析简报，可选择创始人或架构审查
/hamster:resume-hamster [brief]	—	从中断处继续执行
/hamster:review-hamster	资深工程师	两轮严谨代码审查（先审查严重问题，再审查提示性问题）
/hamster:qa [mode]	QA 负责人	系统化测试：基于差异、完整、快速、回归
/hamster:retro [days]	工程经理	基于指标、趋势和团队分析的工程回顾

四个技能带有 -hamster 后缀，因为 Cursor 会将插件技能作为裸 /skill-name 调用，而 ask、plan 和 resume 是 Cursor 自有概念——cursor-agent --mode 接受 plan 和 ask，--resume 则用于选择会话——因此短名称会与它们冲突。review 也改用这一系列名称，以保持 Cursor 命令列表的风格统一。Claude Code 会将插件技能命名空间化为 /<plugin>:<skill>，不会发生冲突，因此在 Claude 中后缀是多余的，输入 /hamster:ask-hamster 即可。一套技能目录服务于所有客户端，这就是在 Cursor 中避免歧义所付出的代价。ship、qa、retro 和 setup 不会与其他名称冲突，因此保持简短。

/hamster:setup

就绪流程。首先进行非交互式检查（ensure-ready）。如果已安装 CLI 且已登录，则运行 hamster sync 刷新计划；否则安装 CLI、打开登录界面，并初始化/同步——仅在你提出请求时执行。

/hamster:ask-hamster

用于向 Hamster 提出开放式问题的入口，这些问题需要 Hamster 综合工作区信息作出判断，例如你正在修改的代码与优先事项、蓝图或决策之间的关系。客户端支持时，通过 ask_hamster MCP 工具提问；否则，hamster chat 会通过 CLI 使用相同的提问流程。直接读取和写入则使用对应名称的 Hamster MCP 工具。例如：

/hamster:ask-hamster I'm modifying auth middleware in apps/web/app/api/. What does our blueprint say about third-party integrations?
/hamster:ask-hamster I prototyped rate limiting in apps/api/middleware/rate-limit.ts. Which brief or initiative should this work belong to?

如果后续问题需要依赖之前的回答，就会继续同一段 Hamster 对话。

/hamster:ship

主协调器。ship、plan-hamster 和 resume-hamster 使用相同的简报选择规则：优先使用 slug、UUID 或 Hamster Studio URL，其次使用完整标题或短标题（即副标题分隔符之前的部分）。名称匹配时不区分大小写，并忽略开头的 “the”、结尾的 “brief” 以及末尾标点。若匹配结果唯一，则直接继续，无需询问选择；若名称匹配存在歧义或仅部分匹配，则需要澄清。

/hamster:ship user-authentication
/hamster:ship the Checkout reliability brief.
/hamster:ship https://tryhamster.com/home/hamster/briefs/2de8d546-50ab-4dbd-a678-579ec8119f60

若未提供参数，则显示可执行简报的交互式选择器。

流程：就绪检查（setup/ensure-ready）→ 设置（先决条件 + 实时同步）→ 选择简报 → 行内安排波次（一次确认）→ 分支 + 合并基准 → 并行执行波次（实现 → 验证 + 测试 → 波次评审 → 可二分提交）→ 最终验证 → 询问是否创建 PR

任何步骤都不会生成计划或细化任务——安排工作只会将预先生成的任务组织成并行波次。

/hamster:plan-hamster

只读分析，可选深度评审。生成执行计划，不做任何更改。

/hamster:plan-hamster api-rate-limiting

分析完成后，选择评审模式：

• CEO 评审（创始人模式） — 从第一性原理出发，进行 10 个部分的深度分析
• 工程评审（架构模式） — 包含 ASCII 图和测试计划的 4 个部分技术评审
• 快速分析 — 仅提供计划

/hamster:resume-hamster

恢复中断的执行。根据 git 分支名称（feature/{key}-{id}-{slug}）、进行中的任务或提供的参数自动检测简报。

/hamster:resume-hamster
/hamster:resume-hamster user-authentication

/hamster:review-hamster

对当前功能分支进行谨慎的两轮代码评审：

• 第 1 轮（关键问题）：SQL 安全性、竞态条件、身份验证边界、枚举完整性、机密信息
• 第 2 轮（信息提示）：副作用、魔法数字、死代码、测试缺口、类型强制转换、时间安全性
• 对关键问题进行交互式处理，可选择修复、确认或标记为误报

/hamster:review-hamster

/hamster:qa

通过 4 种模式进行系统化测试：

/hamster:qa diff        # Test only what changed (default on feature branches)
/hamster:qa full        # Full test suite with coverage
/hamster:qa quick       # 30-second lint + typecheck + smoke tests
/hamster:qa regression  # Changed files + dependents, flag new failures

包含问题分类（功能/类型安全/集成/性能/覆盖率缺口）以及可选的修复循环。

/hamster:retro

根据 git 历史进行工程回顾：

/hamster:retro          # Last 7 days (default)
/hamster:retro 14       # Last 14 days
/hamster:retro 30       # Last 30 days
/hamster:retro 24h      # Last 24 hours

生成内容：指标表、每小时分布、会话分析、热点、PR 大小、每位贡献者的深入分析（包括表扬和成长建议）、与上次回顾相比的趋势，以及叙述性总结。

执行工作器

工作器	角色	用途
task-executor	资深工程师	实现一个父任务及其子任务；加载项目技能、蓝图和方法
wave-reviewer	Staff 工程师	评审整个波次的差异（逐个父任务给出结论 + 跨父任务集成检查），然后进行简化

规范的工作器协议位于 plugins/hamster/skills/ship/references/agents/。plugins/hamster/agents/task-executor.md 和 plugins/hamster/agents/wave-reviewer.md 是基于这些协议正文生成的原生适配器（注册信息 + 模型元数据）；每个支持原生 Agent 的客户端都从同一个文件夹注册它们，但 Gemini CLI（以及使用裸仓库 URL 的 Antigravity）除外，它们会注册不含模型元数据的生成版根目录 agents/ 副本。编辑规范文件后运行 node scripts/sync-adapters.mjs；CI 会检查是否存在偏差。若客户端提供已注册的原生 Agent（Claude Code、Copilot CLI 和 Grok Build 均提供），Ship 会优先使用；否则会启动通用子 Agent 并注入对应的规范正文；若仍不可用，则会在行内运行相同协议。采用通用路径时，如果客户端支持指定模型，task-executor 优先使用能力最强的可用编码模型，wave-reviewer 使用中档模型；否则沿用默认模型。波次安排、分支创建、提交和 PR 创建均在行内完成。 执行者会优先遵循含义明确的简报／规范，而不执行与之矛盾的任务，并记录已解决的计划问题；只有尚未解决或尚未完成的工作才会阻碍任务完成，恢复更新 PR 时也会保留先前对任务和计划反馈所作的处理。

每个技能目录都是自包含的：没有任何 SKILL.md 会读取其他技能的文件，因为客户端可以单独安装或加载任一技能。每个技能都由 SKILL.md 以及可选的 scripts/ 和 references/ 组成；较长的流程放在 references/ 中，以确保技能正文不超过客户端的大小限制（Codex 会读取前 8,000 字节）。共享材料——每个技能 scripts/ 下的就绪检查脚本，以及 references/ 下供 plan-hamster 和 resume-hamster 重新进入流程的协议——会复制到每个需要它们的技能中，而 scripts/validate-plugin.mjs 会对每份副本进行哈希校验，并在它们不一致时使构建失败。根目录的 scripts/ 是维护者工具（sync-adapters.mjs、validate-plugin.mjs、build-codex-bundle.mjs）；它不属于已安装的插件。

plugins/hamster/ 是插件：每个客户端都安装这个文件夹，Gemini CLI 除外，它会安装下文所述的根目录中的生成副本。提交到 Claude 插件目录的也是这个文件夹，该目录只会扫描提供给它的文件夹。这里包含每个客户端的清单（.claude-plugin/、.codex-plugin/、.cursor-plugin/，以及 Antigravity 会读取的 plugin.json）、.mcp.json 和 Antigravity 会读取的 mcp_config.json、skills/、agents/，以及插件自身的 README.md。其中列出了插件会运行、发送和获取的内容，因此这些内容发生变化时也要更新它。仓库根目录保留了指向 ./plugins/hamster 的市场目录（.claude-plugin/，Copilot CLI 也会读取它、.cursor-plugin/ 和 .agents/plugins/）、根目录 package.json（其中 pi.skills 将 Pi 指向相同的技能）、生成的 Gemini 扩展，以及维护者工具、CI 和上架图片。validate-plugin.mjs 会在根目录出现其他插件清单或 MCP 配置时使验证失败，因为 Antigravity 在用户提供裸仓库 URL 时会安装根目录并发现这些文件；它也会在 plugins/hamster/ 内出现任何符号链接或图片时使验证失败，以下情况除外：.claude-plugin/icon.svg（Claude 插件目录的上架图标，必须是自包含 SVG，不含光栅图、脚本或外部引用），以及 assets/ 中的三张 Codex 上架 PNG（必须与根目录 assets/ 中的副本逐字节一致）。build-codex-bundle.mjs 会将根目录的 assets/ 打包到 OpenAI Plugins Directory zip 文件中。Cursor 标志使用指向根目录 assets/logo.svg 的 URL。该 plugin.json 不得声明 Agent Plugins 的 $schema：一旦声明，Copilot CLI 就只会从 com.github.copilot/agents/ 读取 Agent，也不会注册任何 worker。

除生成的 gemini-extension.json 外，根目录唯一的插件清单是 .grok-plugin/plugin.json。Grok Build 的 plugin install <repo> 会读取仓库根目录的清单，且不会跟随市场目录，因此此文件会将 skills、agents 和 mcpServers 指向 plugins/hamster/。这样既能让 grok plugin install gethamster/plugin --trust 继续正常工作，也能让现有的 Grok 安装更新到此布局。agents 必须保持为目录路径：Grok 不会从文件数组中加载 Agent。sync-adapters.mjs 会从 plugins/hamster/plugin.json 写入名称、版本和说明，而 validate-plugin.mjs 会检查每条路径是否有效解析，以及根目录中是否出现其他 <client>-plugin/plugin.json。Antigravity 和 Pi 不会读取 .grok-plugin/，而 Claude 插件目录只会扫描 plugins/hamster/。 不要编辑根目录下的 skills/、agents/ 或 gemini-extension.json。 它们属于 Gemini CLI 扩展，由 sync-adapters.mjs 根据 plugins/hamster/ 生成：skills/ 是精确副本；agents/ 会去掉 Gemini 不接受的 color 行，以及 Gemini 会误读为 Gemini 模型名称的 model 行；gemini-extension.json 则从 plugins/hamster/plugin.json 获取名称、版本和描述，并从 plugins/hamster/.mcp.json 获取托管 MCP URL。GitHub 上的 Gemini CLI 扩展库会列出根目录含有该清单文件的仓库，Gemini 也只会从该文件所在目录旁加载技能和 Agent。提供仓库 URL 后，Antigravity 会安装相同的根目录，并获取相同的 8 个技能、2 个 Agent 和 MCP 服务。编辑 plugins/hamster/，运行 node scripts/sync-adapters.mjs，然后同时提交两者；如果根目录副本存在偏差，--check 和验证器都会失败。

根目录下的 package.json 是 Pi 软件包。Pi 会从仓库根目录安装 Git 仓库，因此其中的 pi.skills 会将 Pi 指向 plugins/hamster/skills；同一个文件也是公开的 npm 软件包 @tryhamster/pi。它包含 pi-package 关键字，Pi 的软件包目录会据此查找 npm 软件包；其 files 字段只会打包技能，npm 还会添加此 README、LICENSE 和 package.json。sync-adapters.mjs 会根据 plugins/hamster/plugin.json 写入该文件，因此插件版本升级会带来新的 npm 版本；如果文件发生偏差、软件包变为私有、关键字丢失或不再打包技能，validate-plugin.mjs 都会失败。要发布版本，请运行 npm pack --dry-run 检查文件列表，然后在仓库根目录运行 npm publish --access public。

编辑共享内容需要同时修改多个文件。 下表每组中的第一个路径是权威来源；其余路径都是必须保持字节级一致的副本。修改来源文件，将其复制到其他文件，然后运行验证器；如果某组存在偏差，验证器会给出确切的 cp 命令。

权威来源	副本
plugins/hamster/skills/setup/scripts/ensure-ready.sh	ship、plan-hamster、resume-hamster
plugins/hamster/skills/setup/scripts/ensure-ready.ps1	ship、plan-hamster、resume-hamster
plugins/hamster/skills/ship/references/brief-selection.md	plan-hamster、resume-hamster
plugins/hamster/skills/ship/references/execution-loop.md	resume-hamster
plugins/hamster/skills/ship/references/agents/task-executor.md	resume-hamster
plugins/hamster/skills/ship/references/agents/wave-reviewer.md	resume-hamster

执行循环

对于每一波并行执行的独立父任务：

Wave N (parallel):
  [task-executor A] || [task-executor B] || [task-executor C]

Post-wave (orchestrator):
  Validation + test gate (one pass, stop on test failure)
  [wave-reviewer] — one worker for the whole wave
    (small low-risk waves: orchestrator reviews inline, no worker)
  Bisectable commits per parent (direct bash)

Git 约定

• 分支：feature/{key}-{lowest-id}-{brief-slug}，其中 {key} 是任务显示 ID 的小写键（HAM-42 → feature/ham-42-…，ACME-7 → feature/acme-7-…）
• 父任务提交：feat({key}-123): 简洁描述（按关注点拆分，以便二分查找）
• 简化提交：refactor({key}-123): 简化描述
• 审查修复提交：fix({key}-123): 处理审查发现的问题
• QA 修复提交：fix(qa): 测试文件 — 描述
• PR：按需创建（不会自动创建），目标为检测到的默认分支

---

进阶：CLI 二进制文件

如果你想在没有插件客户端的情况下使用 hamster 二进制文件，请使用此方法。如果你是通过 Plugins Directory 设置流程跳转到此处的，只需运行安装命令（或下载下方的二进制文件并将其放入 PATH），然后返回设置流程；该流程会为你登录并同步。

curl -fsSL https://tryhamster.com/cli/install | bash
hamster auth login
hamster init
hamster sync

或者从最新版本下载二进制文件。

支持的平台：macOS（amd64、arm64）、Linux（amd64、arm64）、Windows（amd64）。

本仓库中的插件软件包和源文件根据 MIT 许可证授权。通过 GitHub Releases 分发的预构建 hamster 二进制文件依据 Hamster 的商业条款提供。

CLI 命令

命令	描述
hamster auth login	通过浏览器进行身份验证（OAuth 2.1 + PKCE）
hamster auth logout	登出并清除已存储的凭据
hamster init	初始化 Hamster 数据并运行首次同步
hamster sync	从 Hamster Studio 执行一次性同步
hamster sync --watch	通过 WebSocket 持续实时同步
hamster chat "<request>"	在终端中向 Hamster 提问（后续提问使用 --continue）；当插件工具不可用时，使用与托管 MCP 相同的提问路径
hamster status	显示同步状态和统计信息（纯文本输出使用 hamster --no-tui status，技能的就绪检查会运行此命令）
hamster task status <id> <status>	更新任务状态（todo、in_progress、done）
hamster brief status <slug> <status>	更新简报状态

同步的内容

技能会读取当前仓库中的 .hamster/：

.hamster/
  .state.json      # Sync metadata (don't edit)
  {account}/
    briefs/
      {brief-slug}/
        brief.md     # The brief itself
        tasks/       # Parent tasks and subtasks
    blueprints/      # Architecture documents
    methods/         # Team conventions

技能会从 .state.json 中的 account_slug 获取账户目录名称。HAMSTER_ACCOUNT_ID 保存的是账户 UUID，因此设置该变量时，技能会将其与 account_id 核对；如果不匹配，就会停止，而不会猜测。

托管 MCP 工具针对每位用户的一个活跃团队运行，该团队与任何仓库都无关。因此，在首次调用 Hamster MCP 前，以及每次提问或更改前，ask-hamster 都会使用此仓库的 account_slug 调用 switch_account（即你上次在此处运行 hamster sync 时使用的 CLI 团队），并检查切换后所在团队是否具有相同的 account_id。否则，加入多个团队的用户可能会遇到“找不到”实际上存在的任务。服务器会为每位用户保存此选择，因此切换团队也会更改其他 Hamster MCP 客户端使用的团队，直到它们再次切换。如果切换失败或切换到了其他团队，该技能就会停止，并提示你运行 hamster init --force 或使用正确的 MCP 登录方式。其他技能使用 CLI，而非 Hamster MCP，因此不会切换团队。

高级用法：不使用插件的托管 MCP

仅当你想在未安装插件的客户端中使用托管 MCP 工具时，才使用此方式。将 https://tryhamster.com/mcp 添加为远程 MCP 连接器，并通过 OAuth 登录；有关设置、工具列表和客户端注册，请参阅 MCP 服务文档。技能、斜杠命令、CLI 和 /ship 均随插件提供。

---

许可证

MIT。版权所有 Wheel Go Fast, Inc. 有关 Hamster 如何处理你的数据，请参阅 Hamster 的隐私政策。MIT 授权适用于本仓库中的插件包和源文件；通过 GitHub Releases 分发的预构建 hamster 二进制文件则依据 Hamster 的商业条款提供。