セットアップ

このガイドでは、リポジトリをゼロから動作する repo-harness ワークフローへと導きます。ランタイムの インストール、リポジトリの導入、エージェントのフックの接続、そしてガードが発火することの確認を行います。

前提条件

git リポジトリ

repo-harness はリポジトリローカルです。git のワークツリーから実行してください。まだリポジトリで なければ、先に git init を実行します。

エージェント

実行役として 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

2 種類の「インストール」

上記のステップは CLI パッケージ をインストールします。次のステップである repo-harness init は、 このマシン上で ランタイム を構成する別の操作です。同じ言葉でも役割は異なります。そのため、 ブートストラップコマンドは install ではなく init になっています。

2. ランタイムをブートストラップする

1. init はマシンごとに 1 回実行します。冪等です。ホストのフックアダプタ、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-harness adopt

adopt はリポジトリを検査し、ワークフローファイルをインストールし、フックを接続し、CodeGraph インデックスを構築し、ワークフローチェックを実行します。配置されるツリーは次のとおりです。

• AGENTS.md Codex のルーティングコントラクト
• CLAUDE.md Claude Code のルーティングコントラクト
• ディレクトリ.ai/

  • ディレクトリharness/ コントラクト、ポリシー、チェック、ハンドオフ

    • …
  • ディレクトリcontext/ コンテキストマップ + 機能一覧

    • …
  • ディレクトリhooks/ リポジトリローカルなフックランタイム

    • …
• ディレクトリdocs/

  • spec.md プロダクトの真実
• ディレクトリplans/ タイムスタンプ付きプランカタログ

  • …
• ディレクトリtasks/

  • ディレクトリcontracts/ 編集スコープの権限

    • …
  • ディレクトリreviews/ 完了ゲート

    • …
• ディレクトリscripts/ ワークフローヘルパー

  • …

git リポジトリではありませんか？

adopt は git のワークツリー外では実行を拒否します。先に git init を実行するか、git 以外の スキャフォールド向けに repo-harness adopt --repo <path> で明示的なターゲットを渡してください。

4. エージェントを接続する

init は、エディタのイベントを repo-harness へディスパッチする ホストアダプタ をインストールします。 エージェントをそれらに向けたうえで、セッションを再起動してフックを読み込ませます。

Claude Code

アダプタはユーザー設定 — ~/.claude/settings.json — に存在し、SessionStart、PreToolUse、 PostToolUse、UserPromptSubmit、Stop のすべてのイベントをハーネスへルーティングします。 Claude Code を再起動して読み込ませてください。

Codex

Codex は ~/.codex/hooks.json を読み込みます。init がそれを書き込んだあと、Codex の設定で フック設定を信頼 してください。Codex は信頼されていないフックを実行しません。その後、新しい セッションを開始します。

5. 有効になっていることを確認する

1. プロンプトのルーティング — 任意のプロンプトを送信します。UserPromptSubmit フックが意図を 分類し、アドバイザリ出力にプラン状況を表示します。

2. 編集ガード — プランが承認される前に、エージェントにファイルの編集を依頼します。 PreToolUse.edit ガードはフェイルクローズで動作し、プランを記録するまで書き込みをブロックします。

3. ワークフローチェック — ゲートを直接実行します。

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

チェックがグリーンになれば、コントラクトのサーフェスが整合していて、ガードが起動していることを意味します。

6. ChatGPT Pro でプランニングする（任意）

ChatGPT Pro にソースへ触れさせずにプランを読ませたいですか？ローカルの MCP サイドカーを通じて、 ワークフローファイル のみ を公開します。

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。

フック 作業をガードし、トレースする 8 つの管理対象ルート。

CLI リファレンス よく使うすべてのコマンド。