Reef

Reef

コーディングエージェント群のためのバージョン管理。

Reef は Git のコンテンツアドレス方式のストレージを維持しつつ、その作業モデルを、多数の並行して動作する試行錯誤型でトークン制約のある作成者に適したものに置き換えます。この名前は、無数の小さな生物が築く、耐久性のある構造を表す比喩です。

状況：フェーズ 1（リース方式のコピーオンライト・ワークスペース）は完了し、0.1.0（2026-10-25）としてリリースされました。フェーズ 2（型付き API、MCP サーバー、ライブ状態）はすべての終了基準を満たし、0.3.0（2026-11-02）としてリリースされました。macOS と Linux 用のビルド済みバイナリが提供されており、Python と TypeScript の SDK も続いてリリースされます。クイックスタートから始めてください。CLI はまだ安定していません。作業はdocs/dev-ticketsで追跡しています。現在稼働しているものと以下のロードマップをご覧ください。

なぜ

Git は、数十人ほどの人間が 1 日に数回コミットすることを想定して設計されました。エージェントは、その設計の根底にあるあらゆる前提を覆します。

• コミット量が桁違いに増加します。 数十の並行する書き手によって、1 日に何千もの小さな変更が生じます。O（リポジトリサイズ）のコストがかかるものは、すべてボトルネックになります。
• 作業の大半は試行錯誤です。 エージェントはいくつかの方法を試し、そのうち 1 つを採用します。ブランチ作成、スナップショット作成、破棄は、ほぼ無料でなければなりません。
• 履歴を利用する側もエージェントです。 トークンはパフォーマンス指標です。読み込むのに 40k トークンかかる差分は、計算がどれほど速くても遅いままです。
• 競合は日常的に発生します。 2 つのエージェントが同時に同じファイルを編集するのが通常です。モーダル状態でエージェントを停止させる競合は、エージェント群全体を停止させます。
• 信頼の基準は作成者から証拠へ移ります。 人間がすべての行をレビューすることはできません。変更には、まさにこのツリー上でどのテストが実行されたかを検証できる証拠が伴う必要があります。
• Git の儀式は無駄です。 ステージング領域、切り離された HEAD、porcelain 出力の解析はトークンを浪費し、エラーを引き起こします。エージェントが求めているのは型付き API です。

エージェントの分離に対する現在の答えである Git の worktree は、問題を具体化します。各 worktree は完全なコピーであり、依存関係ディレクトリがソースを大きく上回ります。所有者も有効期限もなく、未コミットの作業の唯一のコピーを保持しているため、誰も削除しようとしません。

Reef の独自の仕組み

1. コミットではなくスナップショット。 作業コピーは常にスナップショットです。ステージング領域も未コミット状態もありません。
2. 安定した ID、変更可能な内容。 変更には、リベースや修正後も維持される永続的な ID があります。
3. 競合は第一級のオブジェクト。 マージが競合しても、有効なスナップショットが生成されます。保存したり、解決担当者に委任したり、後で修正したりできます。何も処理をブロックしません。
4. すべて元に戻せます。 グローバルな操作ログにすべての変更が記録されるため、どのエージェントの操作も 1 回の呼び出しで元に戻せます（reef undo <op>）。
5. ワークスペースはキャッシュであり、真実ではありません。 作業ディレクトリはリース方式のコピーオンライトで、エージェントがいなくなると自動的に回収されます。削除しても何も失われません。
6. ハブと一時的なワークスペース。 リポジトリごとに権威あるストアを 1 つ置き、クライアントは必要に応じて遅延フェッチします。完全なクローンは例外です。
7. 証拠は変更に付随します。 テスト結果とビルドハッシュは、署名済みのコンテンツアドレス方式のオブジェクトです。計算に使用したスナップショットにリンクされます。取り込みの可否は、誰がプッシュしたかではなく証拠に基づいて判定されます。
8. API を先に、CLI はその次に。 ローカルデーモンが型付きプロトコルを提供します。CLI と MCP サーバーは薄いクライアントです。ログに対して正規表現を使うエージェントがいてはなりません。

提案はレビューの単位です。main に対して提示される、証拠を伴った変更、または変更のスタックを指します。提案状態にある変更そのものであり、変更 ID で識別されます。プルリクエストはありません。

現在動作する機能

Reef は既存の git リポジトリおよび Jujutsu リポジトリで動作します。リリース 0.1.0 はエージェント向けに git worktree を置き換えるフェーズ 1 で、0.2.0 と 0.3.0 ではフェーズ 2 が追加されます。0.2 からアップグレードする場合は、まず 0.2 からのアップグレード を、0.1 からの場合は 0.1 からのアップグレード もお読みください。

フェーズ 1（0.1.0）

• ローカルデーモン（reef daemon run|start|stop|status）は Unix ソケット経由で gRPC を提供し、状態、設定、ログをユーザーごとの状態ディレクトリに保存します。複数のリポジトリを処理し、チェックアウト内で最初に reef コマンドを実行すると、そのリポジトリが登録されます。通常の git チェックアウトでは、まず jj 側の colocated リポジトリ（.jj/ と .git/info/exclude 内の 1 行）を作成します。
• リース付きワークスペース。 reef ws create は、10 万ファイルのリポジトリでも 1、2 秒（overlayfs では 0.5 秒未満）で変更をワークスペースに展開します。reef ws run は、新しいワークスペース内でコマンドを実行し、プロセスの実行中はリースのハートビートを送り続け、終了時にワークスペースを解放します。reef ws move はリースを手放すことなく、別の変更をワークスペースのディレクトリに配置します。reef ws list|inspect|release でワークスペースを管理できます。エージェントが停止するとリースが期限切れになり、最後のスナップショットがストアに保存され、ディレクトリが回収されます。何も失われません。
• コピーオンライトのバックエンド。 macOS では APFS クローン、Linux ではカーネルの overlayfs または fuse-overlayfs、btrfs と XFS では reflink クローンを使用し、いずれも使えない場合は通常のコピーにフォールバックします。すべて単一の Backend トレイトと適合性テストスイートで統一されています。ワークスペースが消費するディスク容量は、エージェントが変更した内容に比例します。
• 継続的なスナップショット。 ファイルシステムウォッチャー（notify、または大規模なリポジトリでは Watchman）が、デバウンスされた書き込みごとに jj-lib 経由で各ワークスペースのスナップショットを作成します。ウォッチャーによるスナップショットにはローカル専用の印が付けられ、変更が公開されるまでマシンの外に出ることはありません。
• ガベージコレクション。 reef ws gc は、取り消し期間を過ぎた操作、どのワークスペースも使用していないベースキャッシュのエントリー、古いワークスペースの記録を回収し、解放した容量を報告します。
• バックアップと復元。 reef backup <dir> は、エージェントが書き込みを続けている間に、デーモンのデータベースと各リポジトリの jj の状態をコピーします。操作ファイルをコピーする間だけ各リポジトリを一時停止します。reef restore はオフラインで復元し、次回の起動時に、回収することなく、各ワークスペースのディレクトリを最後のスナップショットから再構築します（ADR 0020）。代わりに、クワイエス RPC を使うと、ファイルシステムのスナップショット中にデーモンを静止させられます。
• 共有依存関係ストア。 リポジトリ内の reef.toml で node_modules や target などのストアを宣言できます。reef store build はスクラッチワークスペース内でストアをビルドしてシールし、デーモンはロックファイルのハッシュと照合したうえで、すべてのワークスペースに読み取り専用でマウントします。
• エージェントが使い方を学べる CLI。 reef のみを実行すると 1 画面分のガイドが表示され、reef here は現在のワークスペースと次に実行するコマンドを示します。既知の解決方法があるエラーには、その方法が hint と next コマンドとして表示され、入力待ちになるコマンドはありません（ADR 0025）。
• ベンチマークでは、1,000～10 万ファイルの合成リポジトリを使ってスナップショットのコストとワークスペース作成を測定し、両プラットフォームの結果を CI から公開しています。フェーズ 1 の終了基準に照らした数値は、docs/benchmarks.md をご覧ください。
• オンボーディングのベンチマーク。 Reef を初めて使う実際の Claude Code エージェントに、PATH 上の reef のみを渡し、reef init の実行後、Reef がまだインストールされていない状態で、reef ws run の中から作業させます。動作するワークスペースに到達するまでのツール呼び出し、失敗した reef の呼び出し、トークン数、コストを、各 3 回の試行でオンデマンドに CI 上で測定します。詳しくは docs/onboarding-benchmark.md をご覧ください。

フェーズ 2（0.2.0 と 0.3.0）

• 型付き API と薄い CLI。 デーモンは reef.api.v1 を提供します。これはバージョン管理された protobuf スキーマで、CI では buf による lint と破壊的変更のチェックを行います（ADR 0029）。reef バイナリはこの API のクライアントであり、独自の jj-lib は持ちません（ADR 0033）。
• jj を使わずに変更を確認。 reef status、log、show、diff、describe、abandon、undo、op log、op show、ws snapshot、file read、file list を使うと、ワークスペースまたはチェックアウトからエージェントが行った変更を確認して元に戻せます。各コマンドは JSON を出力し、修正方法が分かっているエラーにはすべて next コマンドが示されます（ADR 0034）。API では、ワークスペースディレクトリがなくても、任意のリビジョンからファイルを読み取り、ディレクトリを一覧表示し、編集を適用できます（ADR 0032）。
• MCP サーバー。 reef mcp は stdio を通じて、RPC にちなんだ名前の 21 個のツールで API をエージェントハーネスに提供します。ツールには、ワークスペース、ステータス、ログ、変更、差分、ファイル（ディレクトリなしでの読み取り、一覧表示、編集）、変更の説明、破棄、操作ログ、取り消し、ファイルまたはシンボルに影響した変更を調べる機能、ほかのエージェントの操作を待つツールが含まれます。reef init は Claude Code、Codex、opencode 用の設定を書き込みます（ADR 0035）。
• リアルタイムの操作。 SubscribeOperations は操作が記録されるたびに操作ログをストリーミングします。リポジトリ、変更、ワークスペース、エージェントで絞り込めるほか、カーソルから再開できます。reef op watch でその内容を表示します（ADR 0036）。ブローカーは各操作を一度読み取り、購読者全員に配信します（ADR 0038）。12 コアの Mac で、毎分 1,000 件の操作に対し購読者が 500 人の場合、p99 配信時間は操作で 53 ms、プレゼンスで 57 ms です（docs/load-tests.md）。
• プレゼンス。 各エージェントが現在何をしているかを示します。アクティビティ、編集中のファイル、リースのハートビート、ワークスペースの作成とストア構築の進捗が含まれますが、永続化はされません（ADR 0037）。reef ws run と reef mcp はそれぞれ独自にプレゼンスを報告し、reef presence report と clear はより詳細なアクティビティを報告します。reef presence watch でプレゼンスを表示でき、reef ws renew では ws run の外部で保持されているリースを更新できます。
• シンボルインデックス。 デーモンは tree-sitter を使って Python、TypeScript、JavaScript、Go、Rust の定義と参照を抽出します。新しいスナップショットや編集をバックグラウンドで処理し、アップロードされた SCIP インデックスも受け付けます。reef symbols index、upload、list で操作できます（ADR 0042）。
• シンボル単位の差分と履歴。 reef diff --symbols は、変更でどの定義が追加、削除、変更、移動されたか、またどの呼び出し箇所に影響するかを示します（ADR 0043）。reef history と MCP の query_changes ツールでは、どの変更がファイルまたはシンボルに影響したか、誰が行ったか、最終的にどうなったか（オープン、取り込み済み、破棄、取り消し）を確認できます（ADR 0044）。
• エージェント向けのサイズに調整された出力。 パイプ経由の出力は簡潔な JSON で、エージェントが操作するキーだけを含みます（ADR 0045）。reef --help はタスク優先の 509 バイトのヘルプです（ADR 0051）。CLI を使った実際の Claude Code 実行では、「このリポジトリの状態は？」への回答に必要なトークン数は、git の 7 分の 1 でした（docs/token-benchmark.md）。reef schema はコマンド、MCP ツール、API を JSON Schema として出力し、ツール定義を生成できます。
• エージェント向けのワンラインインストール。 このリポジトリの Claude Code プラグインと Codex プラグイン、reef init --agents opencode --user、MCP レジストリ上の MCP サーバーを利用できます（ADR 0052）。セッションを git worktree で分離するハーネスは、代わりにワークスペースプロバイダー契約を通じて Reef にワークスペースを要求できます。Claude Code 用のプロバイダーは、オプトイン方式の reef-workspaces プラグインとして提供されます（ADR 0053）。
• ツリーを走査せずにステータスを確認。 ウォッチャーは変更内容のインデックスを保持するため、変更がない場合、100,000 ファイルのワークスペースでもステータス確認は 12 ms で完了します。ツリー走査では 161 ms かかります（ADR 0048）。
• リモートアクセス。 VM 上のデーモンは、スコープを限定でき、失効も可能なトークンを使い、TLS 経由で別のマシンに同じ API と Web UI を提供します（ADR 0049）。
• ローカル Web UI。 reef ui を実行すると、操作ストリームとプレゼンスストリームからリアルタイムに更新される読み取り専用ページがブラウザーで開きます。各リポジトリの最新の操作、smartlog、ワークスペースとエージェント、どのエージェントがどの変更を担当しているか、各リースの状態、ディスク使用量、アクティビティフィードが表示されます。スクラバーを使うと、任意のページを過去の操作時点で再生できます（ADR 0047）。
• タイマーによるガベージコレクション。 デーモンは既定で 1 日ごとに [gc] interval の間隔で reef ws gc を自動実行します。GC を実行しても、ユーザー自身の jj ワークスペースは読み込み可能なままです（ADR 0040、ADR 0041）。 Phase 2 では、Python と TypeScript の SDK を予定しています。行は docs/dev-phases.md にあります。

インストール

エージェントに依頼してください。 Reef を使いたいリポジトリで、コーディングエージェント（Claude Code、Codex、Cursor、またはシェルを使える任意のエージェント）に次のプロンプトを渡します。

Install Reef from https://github.com/reef-vcs/reef, then run `reef init` in this repository and walk me through anything I still need to do.

エージェントが以下のインストーラーを見つけて実行します。続いて reef init がリポジトリを登録します。これにより、git の隣に .jj/ が追加され、Reef のデーモンが起動し、Reef の手順が AGENTS.md に書き込まれます。また、自分用のファイルを読む各エージェントについては、そのリポジトリにすでにファイルがあるエージェントと、Reef が認識する場合は reef init を実行したエージェントのファイルにも書き込まれます。以降のエージェントセッションは、指示がなくてもワークスペースで開始されます。オンボーディングベンチマークでは、Reef を一度も使ったことのない Claude Code エージェントにこのリンクだけを渡したところ、ローカルコピーのインストーラーを使った 0.1.0 以前の測定で、中央値 5～6 回のツール呼び出しでインストールを完了し、ワークスペース内でタスクを完了しました。

自分でインストールすることもできます。 最新リリース 0.3.0 のビルド済みバイナリは、arm64 および x86_64 の macOS と Linux 向けに提供されています。Linux バイナリは静的リンクされているため、任意のコンテナーで実行できます。

curl -fsSL https://raw.githubusercontent.com/reef-vcs/reef/main/install.sh | sh   # ~/.local/bin, no sudo
brew install reef-vcs/tap/reef
cargo binstall --git https://github.com/reef-vcs/reef reef-vcs reef-daemon

インストーラーはリリースの SHA256SUMS と照合して tarball を検証し、確認を求めることはありません。バイナリはまだ署名も公証もされていません（R4.17）。クイックスタートには、インストーラーのオプション、システム要件、tarball の出所を検証する方法が記載されています。

ソースからビルドするには、Rust 1.97.1 以降が必要です。cargo install --locked --git https://github.com/reef-vcs/reef reef-vcs reef-daemon を実行すると、reef と、それが起動するデーモン reef-daemon がインストールされます。これはリリースより先行している可能性のある main をビルドします。reef --version でコミットを確認できます。チェックアウトからは、cargo build --release で両方が target/release にビルドされます。ソースからビルドした場合、先に just web-build（Node 24）を実行しない限り Web UI は含まれません。reef ui を実行すると、その旨が表示されます。0.2 からアップグレードする場合は、まず 0.2 からのアップグレードを、0.1 からの場合は 0.1 からのアップグレードもお読みください。

インストール後、git または jj リポジトリで reef ws run -- <your agent command> を実行すると、新しいワークスペースでエージェントが起動します。reef だけを実行するとエージェントガイドが表示され、reef here を実行すると現在いるワークスペースと次に行うことが表示されます。その他のコマンドは reef --help に一覧表示されます。CI で reef init --check を実行すると、reef init が書き込んだファイルを最新の状態に保てます。標準出力がターミナルでない場合、出力は簡潔な JSON になります（すべてのフィールドを表示するには -o json）。既知の修正方法があるエラーには、実行すべきコマンドが hint および next として含まれます。

ロードマップ

Reef はゼロから作り直すのではなく、Jujutsu のデータモデルと Rust クレートを基盤にしています。各フェーズでは、それぞれ単独でも役立つ成果を提供します。

1. リース付きコピーオンライトワークスペース（完了、0.1.0 としてリリース済み）。overlayfs または APFS クローンを使ってワークスペースを作成し、ファイルシステムウォッチャーでスナップショットを取得し、リースのハートビートを送り、最後のスナップショットを取得して期限切れのワークスペースを回収するデーモンです。共有依存関係ストアのマウントにも対応します。既存の git および jj リポジトリで使えるスタンドアロンツールとして提供されます。これだけでもワークツリーの問題を解消します。
2. 型付き API、MCP サーバー、ライブ状態（すべての終了基準を達成、0.3.0 としてリリース済み。SDK は今後提供予定）。ローカルソケット経由で構造化されたステータス、スナップショット、差分、ログ、取り消しを利用でき、CLI はクライアントとして動作します。ライブ操作およびプレゼンスのストリームを提供します。最初に対応する言語では、シンボルレベルの差分を利用できます。フリートのライブ状態を表示するローカル Web UI もあります。
3. エビデンスオブジェクトとランディングゲート。 アテステーション形式、信頼するアテスターのポリシー、リベースされた提案をまとめ、バッチの先頭でチェックを実行し、失敗時には二分探索するランディングサービスを実装します。トリアージ受信箱は、まず Web UI として提供し、その後デスクトップアプリ、iOS アプリ、Android アプリとして提供します。これにより、人間がどこからでもエージェントを誘導し、承認できるようになります。
4. 共有レイジーオブジェクトストア。 ネイティブプロトコルで通信するストアサーバーを用意し、ローカルキャッシュへのレイジーフェッチと、ストア間のフェデレーションに対応します。
5. 構造的マージ。 Mergiraf を基盤に Tree-sitter を使ったマージを実装し、Python、TypeScript、Go、Rust から対応を始めます。
6. プロトコル仕様と適合性テストスイート。 最初の 4 フェーズが安定した時点で公開し、代替実装が存在できるようにします。

対象範囲

Reef が対象とするのは、特定の組織のモノレポではなく、オープンなエコシステムです。ハブは誰でもホストできるプロトコルであり、信頼性はリポジトリごとに宣言されます。また、導入経路は git との相互運用性です。チームの誰か 1 人が、ほかのメンバーは誰も知らない一般的な GitHub リポジトリに対して Reef を使えることを目指します。

対象外：GitHub やレビュー用プラットフォームの置き換え、ビルドやテストの実行、ホステッドサービスとしての提供。

リポジトリ構成

• crates/reef-error：すべてのクレートが共有するエラー規約です。エラーの種類、分類、アドバイスを定義します。
• crates/reef-lib：コアライブラリです。データモデル、jj-lib の組み込み、スナップショット、操作ログ、取り消しを扱います。
• crates/reef-api：API スキーマ reef.api.v1（proto/reef/api/v1）と、生成された Rust クライアントおよびサーバーです（ADR 0029）。
• crates/reef-client：API の薄いクライアント、安定した JSON、デーモンの検出方法を提供します。jj-lib には依存しません（ADR 0033）。
• crates/reef-broker：ログを一度読み込み、後続のストリームに配信する、メモリ内の上限付きリングです。jj-lib には依存しません（ADR 0038）。
• crates/reef-symbols：シンボルインデックス用の Tree-sitter タグ抽出と SCIP 正規化です（ADR 0042）。
• crates/reef-daemon：ローカルサービスと reef-daemon バイナリです。ワークスペース、マテリアライゼーションバックエンド、ウォッチャー、リース、ガベージコレクション、共有ストア、gRPC サービスを扱います。
• crates/reef-vcs：reef-client のみを基盤とする reef バイナリと、API およびクライアントを再エクスポートする統合ライブラリです。
• crates/reef-testing：未公開のテストフィクスチャと、合成リポジトリの生成ツールです。

設計

設計ドキュメントの全文はdocs/design.mdにあります。作業はdocs/dev-phases.mdでフェーズとチケットに分けられており、各フェーズのチケットにはdocs/dev-ticketsに実装概要があります。エージェントがチケットを引き受けて実装できるように記述されています。

アーキテクチャ上の決定事項はdocs/adrに記録されています。

ベンチマークの内容、測定対象、ベースラインの数値はdocs/benchmarks.mdにあります。200 個のワークスペースでのクラッシュ、再利用、負荷テストはdocs/load-tests.mdにあります。

クイックスタートでは、Reef のインストールからエージェントのワークスペースの再利用までを説明します。

コントリビューション

環境構築、ワークフロー、各コミットで必要な DCO サインオフについてはCONTRIBUTING.mdをお読みください。未完了の作業はdocs/dev-phases.mdのフェーズ 2 の項目と、phase-2ラベルが付いた issue です。

ライセンス

Apache 2.0。