Reasonbook

Reasonbook — セッションを越えて受け継がれる決定事項

Reasonbook（旧称 CMOS）は、エージェントが記録するプロジェクトの記録簿です。何が決まり、その理由は何か、何が分かり、何が残っているかを記録します。 次のセッションでは、別のツールを使う場合でも、その記録をもとに作業を再開できます。 決定を下すのはあなたで、記録管理はエージェントが担当します。ダッシュボードのアカウントは不要です。

Claude Code と Codex で記録された実行を75秒で振り返る動作デモをご覧ください。また、送信・保存されるデータもご確認ください。

Claude Code にインストールする

すべてのプロジェクトで使えるよう、プラグインを一度インストールします。

claude plugin marketplace add kneelinghorse/reasonbook
claude plugin install reasonbook@reasonbook

cmos@cmos からアップグレードしますか？マーケットプレイスを更新する前に、claude plugin uninstall cmos@cmos --scope user（または元の project もしくは local スコープ）を使ってアンインストールし、その後 reasonbook@reasonbook をインストールしてください。ローカルにインストールする場合は、そのプロジェクトからコマンドを実行してください。マーケットプレイスがすでに更新されていて、アンインストール時に「not found」と表示される場合は、テスト済みの復旧手順を使ってください。 既存の記録を移行する前に、すべてのクライアントをアップグレードしてください。

候補版をテストする場合は、kneelinghorse/reasonbook をこのチェックアウトの絶対パスに置き換えてください。インストール後、新しい Claude Code セッションを開始してください。プラグインは MCP サーバー、フック、コマンドを提供します。最初のコールドセッションでは、Reasonbook のインストール中であることが表示され、記録の読み込みは次のセッションになる場合があります。新しい記録には /reasonbook:init、記録の読み込みには /reasonbook:start、作業の完了には /reasonbook:close-out、計画には /reasonbook:plan、実行には /reasonbook:build を使います。プラグインのインストール方法。 その他のツールでは、ハーネスアダプターと対応範囲のガイドをご利用ください。

3つの手順でプロジェクトのダイジェストを取得する

Node.js 20 以降が必要です。

1. 固定バージョンの CLI をインストールします。

   npm install -g @aquex/[email protected]
   

   グローバル npm の bin ディレクトリが PATH に含まれていることを確認してください。以前のパッケージがグローバルにインストールされている場合は、先に npm uninstall -g @aquex/cmos-mcp を実行してください。バージョン 4 で使えるのは reasonbook コマンドのみです。古いコマンドを使っているスクリプトや MCP 設定を更新してください。

2. 記録対象のプロジェクトフォルダーで Ledger を開始します。

   cd /absolute/path/to/your/project
   reasonbook init --level ledger
   

3. 最初のダイジェストを読み込みます。

   reasonbook review --format=context
   

ダイジェストにはこのプロジェクトの名前と、決定事項、学び、未完了の作業が表示されます。新しい Ledger は空の状態で始まります。Planner は次のステップを、Builder はスプリントとミッションを追加します。

Codex プラグイン

開発者向けプラグイン reasonbook は、サーバー、7 つのスキル、5 つのライフサイクルフックを提供します。 会話に特化した reasonbook-chat は、同じサーバーと、異なる 6 つのチャットスキルを提供し、 フックはありません。プラグインの読み込み、インストール、プロジェクトの呼び出しは、バンドル版の Codex CLI と app-server で検証済みです。ChatGPT Work での動作は未検証です。ChatGPT のウェブ版や スマートフォン版でホストされるプラグインではありません。

開発者向けプラグインをインストールします。

codex plugin marketplace add kneelinghorse/reasonbook
codex plugin add reasonbook@reasonbook

以前の名前でプラグインをインストールしている場合は、先に削除してください。どちらのプラグインも同じサーバーとして応答するためです。チャット プラグインの場合は codex plugin remove cmos@cmos と codex plugin remove cmos-chat@cmos を実行します。

チャットのワークフローには、代わりに reasonbook-chat@reasonbook をインストールします。

codex plugin add reasonbook-chat@reasonbook

ローカル開発では、マーケットプレイスのリポジトリをこのチェックアウトの絶対パスに置き換えてください。 両方のプラグインを同時に有効にできます。Codex は rbook という名前のサーバーを 1 つ読み込み、 両方のスキルセットが表示されます。構築には開発者向けプラグインを、セットアップ、状況の把握、想起、意思決定の提案、メモの記録、次のステップの相談にはチャットプラグインを選んでください。

Node.js 20 以降が必要です。プラグインは、既存のインストール向けのレガシー設定のフォールバックを利用して、 Reasonbook の指定バージョンを ~/.config/rbook/plugins にインストールします。初回インストール時は、Reasonbook がインストール中のメッセージとともに接続します。インストールが完了したら、新しいセッションを開始してプロジェクトツールを読み込んでください。開発者向けフックも同じランタイムを使用します。 開発者向けプラグインは、RBOOK_CONFIG_DIR を含む、サポート対象の設定の転送を要求します。 ポータブルなチャットプラグインは、ホストから継承した環境を使用します。空の共有ルートや相対パスは拒否されるため、絶対パスを使用してください。環境変数の転送可否は、クライアントのプラグインローダーによって異なります。ローダーが設定を転送しない場合は、 デフォルトのルートを使うか、サーバーを手動で設定してください。ハーネスガイドを参照してください。

Codex CLI で /hooks を実行し、開発者向けプラグインの 5 つのコマンドを一度確認してください。デスクトップ アプリでその確認画面が表示されない場合は、同じ Codex home を使って、バンドル版の Codex CLI から確認してください。インストール後にプラグインが読み込まれていない場合は、アプリを再起動してください。フック定義を変更した場合は、再度確認が必要です。チャットプラグインにはフックの確認手順はありません。

CMOS 3.3.0 アダプターを置き換える前に、プロジェクトの .codex/hooks.json とユーザーレベルの ~/.codex/hooks.json から、CMOS の項目だけを削除してください。無関係なフックは残してください。 ほかにインポートした CMOS のフック登録も削除してください。応答する MCP サーバーは 1 つにしてください。重複する手動設定を削除するか、意図的に残す場合は、~/.config/cmos-mcp/config.json の "pluginServer": "off" を設定してください（カスタム設定ルートを使う場合は、そのルートの下にある同じファイルを設定します）。

Reasonbook は、サポート対象の Codex 呼び出しごとに指定される作業フォルダーを使うため、プロジェクト内の会話からパスを指定せずに rbook_review() を呼び出せます。そのフォルダーの外では、rbook_project(action="list") で登録済みのアドレスを選び、projectRoot に渡してください。たとえば rbook_review(projectRoot="rbook://you/project") のように指定します。不明または曖昧なアドレスは拒否されます。ローカル専用プロジェクトでは、そのフォルダーを指定する必要があります。ツールのヒントにはテレメトリの削除が保守的に含まれているため、Codex の Auto モードでも、Reasonbook のツールを実行する際に承認を求められる場合があります。

判断を提案し、承認する

選択に承認が必要な場合、エージェントは返信の最後に、具体的な一文を記載します。

Would record: Use a weekly review because it keeps the reading list useful without daily upkeep.

開発者フックを有効にし、その会話にリンクしている場合、Stop フックはこれを下書きとして保持します。次の返信で、承認、却下、質問、または文言の修正を指示できます。エージェントは、返された P<n> ID を付けて承認済みの下書きを記録します。下書きは、まだ判断として記録されていません。プロジェクトフォルダーから下書きを確認するには、次を実行します。

reasonbook drafts list

reasonbook-chat は会話内で承認を求め、会話中に確認されたあなたの言葉をそのコンテキストに残したうえで、直接記録します。Reasonbook は承認を独自に検証できないため、チャットのみの記録について、フックで検証された承認であるとは主張しません。正確な文言への明示的な承認がすでに与えられている場合は、それを承認として扱うため、エージェントが再度尋ねる必要はありません。

方法

• 1 つのプロジェクトに、判断、教訓、制約、次のステップを記録する記録簿を 1 つ用意します。
• その記録簿を出発点とします。対応するフックが、セッションに自動的に取り込みます。
• 理由を添えて、意図的に判断を記録します。判断が変更された場合は、以前の判断に取って代わるものとして記録します。
• 期限切れと置き換えを明示します。スプリントを終了しても、記録はデフォルトで有効なままです。
• ツールを変更しても記録が残るよう、プロジェクトと一緒に保管します。

方法では、5 つの行の全体像、各レベルで Reasonbook が行うこと、次のレベルへの移行方法を説明しています。スターターテンプレートには、各レベルで最初に使うファイルが含まれています。

お使いのマシンから送信されるデータ

記録は、プロジェクトの SQLite ファイルに保管されます。ユーザー単位のキーが保存されている場合、または従来の環境認証情報を使用している場合、明示的なセッション終了とスプリント終了時に、バックグラウンドでファイル全体のアップロードが試行されます。これには、保留中および却下済みの提案も含まれます。登録済みのプロジェクトでは、MCP ツールによる書き込みの後もアップロードがスケジュールされます。書き込みが 5 分間停止したとき、または書き込みが 30 分間継続したときにスケジュールされます。アップロードのリースや失敗後のバックオフによって妨げられない場合、次回のポーリングで 60 秒以内に開始されます。転送にはその後さらに時間がかかります。タイミングと失敗の詳細については、オプション：ホスト型ダッシュボードを参照してください。 RBOOK_CHECKPOINT_SYNC=off を設定すると、自動アップロードと手動の rbook_db(action="backfill") アップロードが停止します。その他の要求されたネットワーク操作や、共有記録のやり取りは引き続き利用できます。 ログアウトしてもプロジェクトキーは有効なままなので、このスイッチがオフでなければ、手動のバックフィルで引き続きアップロードできます。プロセス終了時に暗黙的に行われる終了処理ではアップロードされません。reasonbook.ai を通じて共有されたプロジェクトは、共有記録がダッシュボードのレフェリー用コピーに引き渡されるまで、ファイル全体のアップロードを続けます。その後は、共有記録の変更のみを送信します。記録が元に戻されると、再びファイル全体が送信されます。ネットワーク通信とデータに関する完全な開示。

技術リファレンス

概要

Reasonbook はプロトコルとクライアントです。お使いのマシン上でローカルに動作し、rbook/db/rbook.sqlite に SQLite データベースを保持し、MCP を通じて 15 個の型付きツールを公開します。Claude Code と Codex で動作を確認済みです（ハーネスガイドを参照）。Claude Desktop、Cursor、Zed、VS Code、Windsurf など、その他の MCP クライアントは未テストです。

すぐに次の機能を利用できます。

• 監査可能な遷移を備えた、スプリントとミッションの状態機械
• 判断、学び、制約、次のステップを記録するセッションキャプチャ
• スプリントをまたいで要約される戦略的コンテキストと、FTS5 による検索
• 判断、学び、ミッション、セッションを対象とした全文検索
• 必要に応じたデータベースのスナップショット。スプリント終了時のバックアップ試行。復元前、または行を選択したスナップショットの整理前に必須のバックアップ
• プロジェクトごとの認証情報ストアとデバイスコード認証（RFC 8628）

reasonbook.ai のダッシュボードは任意です。Reasonbook は、いつまでもスタンドアロンで利用できます。サインアップすると、ダッシュボードへのアップロード（SQLite → Postgres ミラー）、プロジェクトレジストリ（rbook://you/* アドレス）、プロジェクト間メッセージングが利用できるようになります。ダッシュボードがなくても、それ以外のすべてのツールをローカルで利用できます。

インストール

推奨：このリリースをグローバルにインストールします。起動時にレジストリを検索せず、サーバーはディスクから起動します。

npm install -g @aquex/[email protected]

以前のパッケージをグローバルにインストールしている場合は、先に npm uninstall -g @aquex/cmos-mcp を実行してください。バージョン 4 で提供されるコマンドは reasonbook のみです。古いコマンドを使用しているスクリプトと MCP 設定を更新してください。

または、npx で必要に応じて実行できます。バージョンを固定し、ローカルキャッシュを優先してください。バージョンを固定しない npx -y は、起動のたびにパッケージを再検索する可能性があります。

npx --prefer-offline -y @aquex/[email protected]

セマンティック（ベクトル）検索は任意です。使用しない場合、検索はキーワードのみとなり、インストール容量は約 306 MB ではなく約 45 MB です。検索にベクトル項目を追加するには、Reasonbook と同じ場所に @xenova/transformers をインストールしてください。rbook_db(action="health") で、インストールされているかどうかを確認できます。

Node.js 20 以降が必要です。

MCP クライアントを設定する

Claude Code と Codex で検証済みです。その他のブロックは各クライアント独自の MCP 設定に従っており、Reasonbook での動作は未検証です。以下の各例では、npx でバージョンを固定して実行し、ローカルキャッシュを優先します。アップグレードするには、バージョンを変更してください。グローバルインストールの場合は、"command": "reasonbook" を指定し、npx の引数を削除してください（例に --project-root がある場合は残します）。

Claude Code

claude mcp add-json rbook '{"command":"npx","args":["--prefer-offline","-y","@aquex/[email protected]"]}'

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または Windows／Linux での同等のファイルに追加します。

{
  "mcpServers": {
    "rbook": {
      "command": "npx",
      "args": [
        "--prefer-offline",
        "-y",
        "@aquex/[email protected]",
        "--project-root",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

Claude Desktop は、プロジェクトコンテキストなしでサーバーを起動することが想定されています（macOS では、ワークスペースルートなしで / から起動します。Reasonbook では未検証です）。そのため、設定でプロジェクト名を指定してください。--project-root は、このサーバーエントリーにのみ適用され、プロジェクトコンテキストがない呼び出しに限って適用されます。つまり、projectRoot もワークスペースルートもなく、作業ディレクトリが /、ホームディレクトリ、またはサーバーのインストールディレクトリである場合です。それ以外のフォルダーからサーバーを起動するクライアントでは、代わりに projectRoot を渡してください。

Cursor

~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "rbook": {
      "command": "npx",
      "args": ["--prefer-offline", "-y", "@aquex/[email protected]"]
    }
  }
}

Zed

{
  "context_servers": {
    "rbook": {
      "command": "npx",
      "args": ["--prefer-offline", "-y", "@aquex/[email protected]"]
    }
  }
}

VS Code（Claude 拡張機能）

統合ターミナルで上記の Claude Code コマンドを使用するか、Claude パネルの /mcp からサーバーを追加します。拡張機能と CLI は MCP 設定を共有します。設定を変更した後は、新しい会話を開始してください。拡張機能はターミナルの PATH に claude を追加しないため、ターミナルから実行するには、単体の Claude CLI が必要です。 VS Code の Claude Code

Windsurf

{
  "mcpServers": {
    "rbook": {
      "command": "npx",
      "args": ["--prefer-offline", "-y", "@aquex/[email protected]"]
    }
  }
}

最初の呼び出し

プロジェクトツールは Reasonbook データベースがあるフォルダーで動作するため、新しいプロジェクトではまず init を実行します。

rbook_project(action="init", projectRoot="/absolute/path/to/your/project")

init は rbook/db/rbook.sqlite、シードファイル、AGENTS.md、およびプロジェクトルートにそれをインポートする CLAUDE.md を作成します（どちらかのファイルがすでに存在する場合は保持します）。このデータベースがないフォルダーでは、プロジェクトを読み書きするツールは処理を拒否し、init の実行を案内します。レジストリとサインインの操作にはプロジェクトは不要です。

次に、rbook_agent_onboard を一度実行します。新しいプロジェクトでは、最初のセッションのセットアップが案内されます。その後の各セッションは、セッションダイジェストから始めてください。

Run rbook_review to see the project state.

rbook_review は、共有セッションダイジェスト（プロジェクトの概要、現在のスプリント、未完了の作業、最近の決定事項）を返します。ローカルのテキストコアは 4,000 文字までです。追加されるポートフォリオコンテキストと、それを囲む MCP レスポンスはこの上限に含まれません。

インストール → 設定 → init → 最初のスプリント／ミッション／セッションのサイクルまでを含む完全な手順は、docs/getting-started.md にあります。

ツールの概要

Reasonbook は、15 個の統合ツールを公開しています。12 個のツールでは、action パラメーターで操作を選択します。rbook_agent_onboard、rbook_status、rbook_review では action は不要です。TOOL_REFERENCE.md には操作ごとにパラメーターテーブルが記載されているため、各呼び出しで実際に適用されるパラメーターを確認できます。

ツール	目的
rbook_review	セッションの要約：ID、スプリント、作業、決定事項、他プロジェクトからのシグナル
rbook_agent_onboard	コールドスタート用ペイロード：ID、アクティブなスプリント、ミッション、決定事項、提案
rbook_status	診断スナップショット：rbook_address、dashboard_url、auth_tier、同期のタイムスタンプ
rbook_mission	ミッション — 作成、更新、照会、依存関係のリンク
rbook_mission_transition	ミッションの状態遷移 — 開始、完了、ブロック、ブロック解除、破棄、延期
rbook_sprint	スプリント — CRUD、終了処理、振り返り、スプリント横断の分析
rbook_session	作業セッション（任意）— 開始、インサイトの記録、完了、一覧表示、検索
rbook_context	マスター／プロジェクトのコンテキスト — 表示、更新、要約、スナップショット、検索
rbook_decisions	戦略的な決定事項 — 記録、表示、一覧表示、検索、更新、陳腐化の確認
rbook_learnings	複数領域にまたがる学び — 一覧表示、検索、表示、更新、再確認
rbook_db	データベース操作 — ヘルスチェック、スナップショット／復元、バックフィル、コンテキストスナップショットの削除
rbook_project	プロジェクト — 初期化、登録、一覧表示、検証、共有、招待、参加、メンバー、同期
rbook_auth	ダッシュボードの認証情報のライフサイクル — デバイスコードでのログイン、ローテーション、失効
rbook_message	プロジェクト間のメッセージング（ホスト型ダッシュボードが必要）
rbook_feedback	エージェントフィードバック用チャネル — 一覧表示、トリアージ、解決、アーカイブ

操作ごとの正確なパラメーターリファレンスについては、TOOL_REFERENCE.md を参照してください。これはビルドのたびにツール定義から生成されるため、リリース済みのツール構成と食い違うことはありません。

プロジェクトの記録を共有する

オーナーはプロジェクトを編集者と共有できます。各自が完全なローカルコピーを保持してローカルで作業し、reasonbook.ai（プロジェクトの基準となるコピーを保持し、ダッシュボードに表示します）を通じて変更を交換するか、SSH 経由または手渡しのバンドルでオーナーのコピーと直接変更を交換します。競合するフィールド値は、誰かが解決するまで表示されたままになります。

共有は、実測済みの構成でサポートされています。1 人が 2 台のマシンで 2 つのアカウントを操作し、reasonbook.ai 経由、または SSH 経由でオーナーとメンバーのペアとして共有する構成です。別の人との共同作業やプライバシーに関する体験は、まだ検証されていません。編集者の行は、外部ソースとの境界線が設けられないままオーナーのエージェントにとってのローカルなプロジェクトコンテンツになるため、記録の内容を信頼できる人を招待してください。

reasonbook.ai 経由の場合、各自が自分のマシンでサインインします。オーナーのエージェントがプロジェクトを共有し、オーナーがダッシュボードで編集者と共有します。その後、編集者はプロジェクトのページにある参加用の文を自分のエージェントに渡します。オーナーのコピーは、rbook_project(action="move", to="owner") または reasonbook move --to owner でプロジェクトを戻し、その後 SSH 経由でメンバーのコピーを最新の状態にできます。メンバーは reasonbook sync --confirm-owner で移動を確認します。これは、メンバーが 1 人参加した状態で、rbook_project を通じて移動を行い、実環境で測定済みです。1 台のマシンで保持できる共有プロジェクトのライブコピーは 1 つです。

まずは共有手順と信頼境界をご覧ください。SSH 経由の共有にダッシュボードアカウントは不要です。フックが実行される環境では、セッションの開始時と終了時に自動で変更を交換します。また、サーバーが保存済みルートを使って開いた共有プロジェクトでは、5 分ごとに変更を交換します。RBOOK_SHARED_SYNC=off を設定すると、これらの自動交換は停止します。明示的な同期コマンドとバンドルコマンドは引き続き使用できます。

オプション：ホスト型ダッシュボード

ダッシュボードは独立したサービスです。reasonbook.ai で登録すると、以下を利用できます。

• ダッシュボードミラー — SQLite ファイル全体のスナップショットをアップロードし、ダッシュボードに表示します。
• プロジェクトレジストリ — マシン間で参照できる rbook://you/project-name URI。
• メッセージング — 自分のプロジェクト間で rbook_message(action="send") を使用します。
• 共有 — プロジェクトの記録を編集者と共有できます。編集者はプロジェクトのページから参加します。ダッシュボードは記録の正本を保持し、記録、メンバー、および各自が作成・移動した内容のフィードを表示します。プロジェクトの記録を共有するをご覧ください。

接続するには：

export RBOOK_DASHBOARD_URL=https://reasonbook.ai

次に、エージェントから rbook_auth(action="login_init") を実行します。一度だけ使用できる userCode と verificationUri が返されます。ブラウザーで URL を開いてコードを入力し、その後 rbook_auth(action="login_complete", deviceCode=...) を実行して完了します。認証情報は ~/.config/rbook/credentials.json にアトミックに保存されます（モード 0600）。

RBOOK_DASHBOARD_URL のデフォルトは https://reasonbook.ai です。ダッシュボードの認証情報がない場合、ダッシュボード操作は rbook_auth(action="login_init") を示す構造化された DASHBOARD_NOT_CONFIGURED エラーを返します。ローカルツールと共有記録の直接交換は、ダッシュボードなしで動作します。

ユーザー単位のダッシュボードキー、または従来の環境認証情報が保存されている場合、明示的な rbook_session(action="complete") および rbook_sprint(action="complete") の呼び出しは、バックグラウンドでのアップロードを試み、先にプロジェクトを登録することがあります。登録済みプロジェクトでは、ストアに実際に書き込む MCP ツール呼び出しもアップロードをスケジュールします。アップロードは、5 分間書き込みがない場合、または書き込みが継続して 30 分経過した場合に実行対象となり、アップロードリースや失敗時のバックオフによってブロックされていなければ、その後 60 秒以内に開始されます。実行中のサーバーでプロジェクトを開いている必要があります。短時間だけ実行されるプロセスが残した未処理の作業は、次のサーバーに引き継がれます。各アップロードでは、保留中、却下済み、期限切れの提案を含む SQLite ファイル全体の一貫したスナップショットを送信します。転送時間はこれに加わります。また、同時に動作するサーバー間で、プロジェクトごとに 1 つのアップロードリースを共有します。

アップロード結果と失敗は rbook_status と rbook_review に表示されます。HTTP 401、402、403 が返された場合、明示的な終了処理が成功するまで自動再試行は一時停止します。アップロードに失敗しても、ローカルへの書き込みや終了処理は失敗しません。プロセス終了時に暗黙的に実行される終了処理ではアップロードされません。自動アップロードと手動バックフィルを無効にするには、サーバー環境で RBOOK_CHECKPOINT_SYNC=off を設定します。明示的な同期、メッセージング、サインイン、共有記録の交換は無効になりません。ログアウトするとユーザー単位のキーは失効しますが、プロジェクトキーはダッシュボードへのリクエストに引き続き有効です。SECURITY.mdをご覧ください。

プロジェクトの解決

Reasonbook は、指定されていないプロジェクトに対して処理を行いません。各ツール呼び出しでは、次の順序でプロジェクトを 1 つ選び、そのプロジェクトを使用できない場合はフォールバックせずに拒否します。

1. 呼び出しの projectRoot パラメーター：プロジェクトフォルダー、または登録済みの正確な rbook://owner/project アドレスです。アドレスの検出では、保存済みの ID を修復せずに読み取ります。一致するものがない場合、複数一致する場合、または登録済み ID を読み取れない場合は拒否します。
2. サポート対象の Codex リクエストの場合は、その会話の作業フォルダーです。指定されたフォルダーが無効な場合、サーバーのフォルダーにフォールバックせずに拒否します。
3. MCP クライアントが通知するワークスペースルート：Reasonbook プロジェクト内にある最初のルートです。
4. 作業ディレクトリ、またはその上位で最も近い Reasonbook プロジェクトのフォルダーです。Reasonbook プロジェクトとは rbook/db/ を含むフォルダーです。rbook という名前の通常のフォルダーは該当しません（ホームディレクトリより下まで検索します）。
5. サーバーにプロジェクトのコンテキストがまったくない場合に限ります（projectRoot もルートもなく、作業ディレクトリが /、ホームディレクトリ、またはサーバーのインストールディレクトリの場合。プロジェクトフォルダーを指定せずにサーバーを起動するクライアントがこれに該当します）。その場合は、まずサーバーの設定にある --project-root <dir> 引数を使い、次に rbook_project(action="register", projectRoot="...", setAsDefault=true) で設定されたレジストリのデフォルトを使います。
6. それ以外の場合、呼び出しは拒否されます。Reasonbook プロジェクトではないフォルダーで書き込みを行うと、rbook_project(action="init") を指定します。読み取りでは "No Reasonbook project in ''" と応答します。

rbook_project(action="list") には、保存済みの ID、アドレス、フォルダーが含まれます。init、register、unregister にはフォルダーが必要です。アドレスがファイルシステムのパスとして扱われることはありません。

成功した応答では、使用したプロジェクトを projectRoot と resolvedBy でデータ内に示します。また、プロジェクトがワークスペースルート、--project-root、またはレジストリのデフォルトから取得された場合は、応答テキストでもそのことを伝えます。3.2.0 より前に設定されたレジストリのデフォルトは、setAsDefault を再実行するまで適用されません。デフォルトがある場合は、サーバー、rbook_message(action="whoami")、rbook_review がそのことを伝えます。

作業を中央の計画フォルダーから移動する

1 つの Reasonbook プロジェクトに複数の取り組みをまとめている場合、ある取り組みに独自のプロジェクトフォルダーが必要になったら、spin-out を使用します。選択したミッションと、それにリンクされた決定事項、学び、次のステップ、および指定した追加のレコード ID をコピーします。移動元には、新しいプロジェクトへのポインターを含む、参照可能な履歴が残ります。

先に移動先フォルダーを作成してください。移動元は登録済みである必要があり、2 つのストアではプロジェクト ID が異なっている必要があります。両方のルートを指定してください。このコマンドは、暗黙のプロジェクトやレジストリのデフォルトを使用しません。選択内容とマッピングをプレビューするには、--apply を省略します。

reasonbook spin-out --from /work/projects --to /work/new-product --sprint sprint-12

# Or select missions, with additional decisions, learnings and next steps by ID:
reasonbook spin-out --from /work/projects --to /work/new-product \
  --missions product-plan,product-prototype \
  --decisions 41,42 --learnings 17 --next-steps 23,24

# Apply the same reviewed selection:
reasonbook spin-out --from /work/projects --to /work/new-product \
  --missions product-plan,product-prototype \
  --decisions 41,42 --learnings 17 --next-steps 23,24 --apply

--sprint または --missions のいずれかを選択してください。移動先に Reasonbook がない場合、プレビューでは初期化が必要であると報告されます。--apply を指定すると、コピーの前に移動先が初期化され、データベースのバックアップが作成されます。コピーされた作業はステータスを維持しますが、移動先でスプリントには割り当てられません。準備ができたら、対象のスプリントに割り当ててください。移動元の Queued、Blocked、Deferred のミッションは Dropped になり、Completed と、すでに Dropped のミッションはステータスを維持します。移動元の決定事項と学びはアーカイブされ、移動元の次のステップはドロップされます。デフォルトのリストと取得結果には、移行された移動元の行は含まれません。スプリント履歴には件数が維持され、移動先へのポインターによって移行が示されます。スプリントが自動的に終了することはありません。

移動元またはコピー先の決定事項、学び、ミッションを読むには、既存の show アクションと明示的な projectRoot を使用します。結果には spunOutTo または spinOutOrigin と、読み取り可能なアドレスが含まれます。履歴上の次のステップには、次を使用します。 rbook_context(action="next_steps", nextStepAction="list", nextStepIds=[23], projectRoot="/work/projects")。 明示的に指定した ID には、移動済みまたはドロップ済みの行も含まれます。ただし、明示的に nextStepStatus を指定した場合は、それによる絞り込みが適用されます。通常の次のステップのリストには、引き続き未完了の作業が表示されます。スプリントに割り当てられていない移動先の次のステップは、42 日後にアイドルとしてフラグ付けされます。CLI はどちらのストアもすぐにはアップロードしません。それぞれ、次回の MCP 書き込みが成功した後、設定済みのアップロード制御に従って通常のアップロードスケジュールに入ります。

中断した場合は、同じコマンドをそのまま再試行してください。完了が検証済みの操作は、変更なしで返されます。移動先へのコピーが確定した後に移動元のレコードが変更された場合、最後の移動元へのマーク付けは拒否され、両方のストアが確認用に保持されます。予約済みの再試行に、確定済みの移動先の受領記録がない場合も、コマンドは拒否されます。コピー前のクラッシュなのか、以前のコピーの証明が消去されたのかを判別できないためです。対処方法に記載された両方のルートと操作 IDを保持し、それぞれの台帳と書き込み前のスナップショットを確認してから、再試行の前に競合状態を解決するか、復元してください。別のコピーを強制するために予約を削除しないでください。再試行によって、コピー済みの作業が暗黙に上書きされることはありません。

環境変数

# Optional — connects to the hosted dashboard. Defaults to https://reasonbook.ai
# when unset; treat empty string as unset.
RBOOK_DASHBOARD_URL=https://reasonbook.ai

# Optional — the directory the server reads its own .env from. It does NOT select a project:
# use the projectRoot parameter, or --project-root in a server's config.
RBOOK_PROJECT_ROOT=/path/to/your/project

# Optional — override the credential + registry directory. Default: ~/.config/rbook
RBOOK_CONFIG_DIR=/custom/path

# Snapshot retention (default shown)
RBOOK_MAX_SNAPSHOTS=50

# Optional — disable background uploads after writes and explicit completion calls.
# Shared-store propagation and explicitly requested network actions remain available.
RBOOK_CHECKPOINT_SYNC=off

# Optional — disable shared-record exchanges started by hooks and the server timer.
# Explicit reasonbook sync and bundle commands remain available.
RBOOK_SHARED_SYNC=off

# Optional — turn off starting a share or a join through reasonbook.ai on this machine
# (off, false, 0 or no, in any case). On by default; a project already shared through the
# dashboard syncs either way.
RBOOK_DASHBOARD_SHARING=off

エラーレスポンスの形式

すべてのツールは、統一されたエンベロープを返します。

{
  "success": false,
  "error": {
    "code": "MISSION_NOT_FOUND",
    "message": "Mission 's99-m01' not found",
    "suggestion": "Use rbook_mission(action=\"list\") to see available missions"
  }
}

code は機械可読、message は人間が読める形式、suggestion は具体的な次のステップです。検証エラーには validValues（string[]）が含まれます。状態エラーには currentState が含まれる場合があります。関連するミッション、セッション、またはスプリントの状態が取得できる場合は通常、ステータス文字列です。ただし、SESSION_ALREADY_ACTIVE の場合に限り、オブジェクト { id, type, title, startedAt, captureCount } になります。読み取る前に code に基づいて分岐してください。

安全性

• 追記専用の監査ログ。 セッションイベントとミッションの遷移は、追記専用の行として記録されます。コンテキストスナップショットの行、ID、イベントは保持されますが、rbook_db(action="prune_snapshots") を使うと、Reasonbook が独自に書き込んだコピーの内容を空にできます。
• 認証情報のアトミックな書き込み。 credentials.json は一時ファイルへの書き込みとリネームで保存され、権限は 0600 に設定されます。
• データベースのスナップショット。 rbook_db(action="snapshot") は、必要に応じてデータベースをコピーします。rbook_sprint(action="complete") は完了前と完了後にスナップショットの作成を試みます。作成に失敗した場合は警告が表示されますが、完了は妨げられません。選択対象が空でない場合、rbook_db(action="prune_snapshots") を適用するにはバックアップが必要です。また、rbook_db(action="restore") は、まず稼働中のデータベースを rbook/db/snapshots/pre-restore/ にコピーします。RBOOK_MAX_SNAPSHOTS は保持するスナップショットの数に上限を設けます。スナップショットを作成すると、上限を超えた分の最も古いものが削除され、自動作成されたものも対象になります。それ以外の操作では事前にスナップショットは作成されず、ソフト削除の保護策もありません。rbook_db(action="purge") は、このプロジェクトのデータをダッシュボードミラーから削除します。また、reasonbook.ai を通じてプロジェクトが共有されている間は実行できません。SECURITY.md を参照してください。
• ドライランは対応している箇所のみ。 rbook_context(action="condense") は、変更を確定せずにプレビューするための dryRun を受け付けます。変更を行うツール全般に備わる機能ではありません。バックフィルの旧イベント再生ドライランは廃止されており、LEGACY_SYNC_RETIRED を返して拒否されます。

既知の制限

• 共有レコードがプロトコル 2 に切り替わるのは、すべての稼働中のコピーがサポートを報告した後だけです。rbook_review には、切り替えを妨げているコピーが表示されます。切り替え前は、ID の取得は既存のクロック順に従います。切り替え後は、最初にカウントされた承認によってクレームの位置が固定され、切り替え前のクレームはそれ以降のクレームより優先されます。また、コピーがそれ以前の位置にあるすべてのクレームのデータを保持すると、承認済みの ID が確定します。予測可能な ID が先に取得される可能性は引き続きあります。復旧では、これまで判定されていないトランザクションをクロック順に判定します。停止の原因となっているコピーは、切り替えを妨げないように切り離す必要があります。reasonbook.ai では、この操作をオーナーページから実行するには、ホスト側で切り離し機能をデプロイする必要があります。
• プロトコル 2 への切り替え後、古いリーダーに届く各ストリームは、最初のプロトコル 2 による変更を含むトランザクション全体の直前までです。古いリーダーや未報告のリーダーへの参加、後継者の指定、計画的な移行は拒否されます。ダウングレードすると、ID がローカルで変更されることがあります。 古いコピーは自身の書き込みを引き続き送信しますが、その境界を超えたデータは受信しません。古いオーソリティは、メンバーによるプロトコル 2 の書き込みを保持します。共有作業を続ける前に、すべてのコピーをアップグレードしてください。復旧では、切り替えが採用されたオーソリティのプレフィックスに含まれる場合に限り、その切り替えが維持されます。
• ダッシュボードの認証情報を持つ登録済みプロジェクトは、サーバーの実行中に書き込み後および明示的な終了時にスナップショットをアップロードします。手動での rbook_db(action="backfill") は、ファイル全体をただちにアップロードするよう要求します。共有レコードの交換には、専用のフック、タイマー、RBOOK_SHARED_SYNC 制御が使われます。
• SQLite が信頼できる唯一の情報源であり、ダッシュボードにはオーナーがアップロードしたミラーが保存されます。共有コピーは、reasonbook sync を使い、reasonbook.ai 経由、SSH 経由、またはバンドル経由でレコードを交換します。
• reasonbook.ai 経由でプロジェクトを移行した後に戻す処理の計測では、メンバーが 1 人で自動同期を無効にした状態において、メンバーのコピーが移行後にダッシュボードと同期する前に、オーナーのコピーが SSH 経由でメンバーのコピーを追いつかせました。自動同期が有効な場合は、メンバーのコピーが先に同期する可能性があります。未計測のケースは、メンバーのコピーが先にダッシュボードと同期し、その同期によってオーナーのコピーとの SSH 同期またはバンドル同期が指示されるケースと、オーナーのマシンから SSH で到達できないメンバーのコピーです。ダッシュボードのアクティビティフィードには、デフォルトで 1 ページあたり 50 件、最大 100 件が表示され、判定ページには 1 ページあたり 20 件の判定が表示されます。以前のエントリは後続のページにあります。
• reasonbook.ai 経由で共有されたプロジェクトは、メンバーのエージェントを通じて変更されます。ダッシュボードのページにはレコードが表示されます。レフェリーライブラリは、残存するコピーからの復旧と、メンバー／アカウントの紐付けを維持したままの移行後の再共有をサポートします。これらを利用するには、ダッシュボードの対応するルート、保存済み履歴、オーナー向け制御機能をデプロイする必要があります。それまでは、ホスト上のコピーを失うとホスト経由の共有は引き続き停止し、古いホスト経由ではメンバーを安全に復元できません。各メンバーは自身のローカルコピーを保持します。
• reasonbook.ai 経由の共有では、書き込みを行った、正常に交換した、または SSH 経由のルートを保持しているオーナーの他のコピーについて、名前を示して拒否します。これには、確認済み、またはルートが設定された元オーナーのコピーも含まれます。ダッシュボードルートの行、切り離されたコピー、このフォルダーの以前の ID は対象外です。直接のオーソリティコピーで reasonbook set-aside --replica <id> を実行すると、停止したコピー 1 つが保持するカットオフと最後の交換内容をプレビューできます。記録するには --yes を追加します。その人の他のコピーはメンバーのままです。ロールの変更、削除、再受け入れを行っても切り離し状態は維持されます。その人の後続の書き込みは隔離され、本人がやり直す必要があります。また、復旧でそのコピーを待つことはありません。ホストされたプロジェクトでは、レフェリーライブラリによってダッシュボード専用の setAside 操作が提供されます。過去 7 日以内に接続したコピーには明示的な確認が必要です。オーナーページからこの操作を実行できるようにするには、reasonbook.ai がデプロイする必要があります。ダッシュボードがレフェリーを担当している間、ローカルでの管理操作は拒否されます。
• 切り離しを含むレコードでは、計画された引き継ぎ先またはダッシュボード共有先で、報告済みライブラリバージョンが 4.5.0 以降である必要があります。不明な報告も拒否されます。また、共有ではアップロード前に確認されます。4.5.0 より前のバイナリで実行した reasonbook recover は、切り離しを取り消すことがあります。 復旧用コピーは、使用前にアップグレードしてください。旧 rbook_db(action="clone") および rbook_db(action="pull") アクションは LEGACY_SYNC_RETIRED を返して拒否されます。これらのアクション値は 5.0.0 まで残ります。

ドキュメント

• ドキュメントのホーム — 概要、インストール方法、各レベル、詳細情報の参照先を説明します。
• ハンドオフのデモ — 記録された実行をトランスクリプト付きで75秒間再生します。
• 信頼性 — マシンの外部に送信されるデータ、フックが読み取る内容、各部分を無効にする方法を説明します。
• プライバシー — 収集、ダッシュボードでの表示、保持、削除について説明します。
• 手法 — 5つの行、3つのレベル、上位レベルへの移行方法を説明します。
• はじめに — クライアントの設定と、任意で利用できるBuilderの手順を説明します。
• ハーネスの対応状況 — ネイティブアダプター、MCP プロンプト、フックを使わない場合のフォールバックについて説明します。
• ツールリファレンス — すべてのツール、アクション、パラメーターを掲載しています（ツール定義から生成）。
• 変更履歴 — リリースノートとツールの変更点を掲載しています。

開発

git clone https://github.com/kneelinghorse/reasonbook
cd reasonbook
npm install
npm run build
npm test

開発にはNode.js 20.17以降（lint-staged 16.4）が必要です。公開済みパッケージはNode.js 20以降で動作します。

コミット前フックはhusky/lint-stagedを使ってlintとフォーマットを実行します。この公開リポジトリはコードミラーです。リリースの検証とnpmへの公開は、非公開のソースから実行されます。

ライセンス

Apache-2.0。LICENSEおよびNOTICEを参照してください。