安装

本指南把一个仓库从零带到可用的 repo-harness 工作流：安装运行时、采用仓库、接好 agent 的 hook，并确认护栏会触发。

前置条件

一个 git 仓库

repo-harness 是 repo-local 的。请在 git 工作树中运行——如果当前目录还不是仓库，先 git init。

一个 agent

用 Claude Code 或 Codex CLI 作为执行器。ChatGPT Pro 是可选的，用于规划。

Bun

CLI 运行在 Bun 上——如果缺失，安装脚本会自动拉取。无需配置 Node。

1. 安装 CLI

用最适合你的入口把 repo-harness 二进制装到机器上：

curl

# macOS / Linux — installs Bun if missing, then the CLI
curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh

bun

bun add -g repo-harness

npm

npm install -g repo-harness

两种不同的“安装”

上面这一步安装的是 CLI 包。下一步 repo-harness init 是另一个动作，用来在本机配置运行时。同样是“安装”这个词，做的却是两件事——这也是为什么引导命令叫 init 而不是 install。

2. 引导运行时

1. 每台机器只需运行一次 init。它是幂等的——它会为你将来用到的每个项目接好宿主 hook 适配器、Waza 技能和 CodeGraph 索引：

   repo-harness init
   # ✓ host adapters · skills · CodeGraph configured

2. 随时检查就绪状态（只读）：

   repo-harness status   # CLI version, host install state, route coverage
   repo-harness doctor   # PATH, version, hosts, trust state

已经引导过了？

repo-harness init 可以安全地重复运行——用它来修复配置了一半的机器。之后要拉取更新的运行时，使用 repo-harness update。

3. 采用你的仓库

1. 在仓库根目录下预览将要发生的改动。不会写入任何内容：

   repo-harness adopt --dry-run   # Migration Report

2. 应用 repo-local 契约：

   repo-harness adopt

Adopt 会检查仓库、安装工作流文件、接好 hook、构建 CodeGraph 索引，并运行工作流检查。它铺设的文件树：

• AGENTS.md Codex 路由契约
• CLAUDE.md Claude Code 路由契约
• 文件夹.ai/

  • 文件夹harness/ 契约、策略、检查、handoff

    • …
  • 文件夹context/ context-map + capabilities

    • …
  • 文件夹hooks/ repo-local hook 运行时

    • …
• 文件夹docs/

  • spec.md 产品事实
• 文件夹plans/ 带时间戳的计划目录

  • …
• 文件夹tasks/

  • 文件夹contracts/ 编辑范围授权

    • …
  • 文件夹reviews/ 完成门禁

    • …
• 文件夹scripts/ 工作流辅助脚本

  • …

不是 git 仓库？

Adopt 拒绝在 git 工作树之外运行。先运行 git init，或者用 repo-harness adopt --repo <path> 显式指定目标来做一个非 git 的脚手架。

4. 接线你的 agent

init 会安装把编辑器事件派发进 repo-harness 的宿主适配器。把你的 agent 指向它们，然后重启会话让 hook 加载。

Claude Code

适配器位于你的用户设置中——~/.claude/settings.json——它把每个 SessionStart、PreToolUse、PostToolUse、UserPromptSubmit 和 Stop 事件路由进 harness。重启 Claude Code 以加载它。

Codex

Codex 读取 ~/.codex/hooks.json。在 init 写好它之后，在 Codex Settings 中信任该 hook 配置——Codex 不会执行未受信任的 hook。然后开启一个新会话。

5. 验证已生效

1. Prompt 路由——提交任意 prompt。UserPromptSubmit hook 会对意图分类，并在其建议性输出中展示计划状态。

2. 编辑护栏——在任何计划被批准之前，让 agent 编辑一个文件。PreToolUse.edit 护栏会 fail closed，在你捕获计划之前阻止写入。

3. 工作流检查——直接运行门禁：

   bash scripts/check-task-workflow.sh --strict

绿色的检查意味着契约面是一致的，护栏已就位。

6. 用 ChatGPT Pro 规划（可选）

想让 ChatGPT Pro 读取你的计划而不碰源码？通过本地 MCP sidecar 只暴露工作流文件：

repo-harness mcp setup chatgpt --repo .
repo-harness mcp serve --transport http \
  --host 127.0.0.1 --port 8765 --profile planner

完整细节——包括只读安全边界——见 ChatGPT Pro 规划器页面。

下一步

工作流 Plan → Sprint → Goal，以及 Human Review Card。

Hooks 守护并追踪你工作的八条托管路由。

CLI 参考 你会用到的每一条命令。