Waypoint

Waypoint

Waypoint は AI コーディングツール間でプロジェクトごとのログを共有し、作業がどこで止まったか、次に何をするかを確認できるようにします。

ウェブサイト： waypoint.stifler.in

プロジェクトを切り替えたり、Claude Code、Codex、ChatGPT を使い分けたりします。それぞれのツールには独自のメモリがありますが、ほかのツールが何をしたかはわかりません。Waypoint は、プロジェクトごとに同じ記録（プロジェクトの内容、前回の作業地点、次にすること、注意が必要なこと）をすべてのツールに共有し、その記録が実際の活動に追いついていない箇所も示します。

たとえ話： 各プロジェクトは航海、各 AI ツールは航海士、そして航海日誌は全員が書き込む船のログです。ダッシュボードは海図です。

Waypoint が扱う真実は 2 種類です。

• 事実（場所と時刻）：どのプロジェクトか、どのツールか、いつか、最後のコミットは何か。Waypoint はツールのローカル履歴と git から、これらを自動的に収集します。
• 意味（何を、なぜ）：何を完了したか、次に何をするか、何が妨げになっているか。AI ツールが、共通のルールに従って短いログエントリーに書き留めます。

両者が食い違うと、海図にそのことが示されます。プロジェクトで作業したのに何も記録しなかったツールがあると、未記録の当直（セッション）が残ります。ツールがルールを忘れた場合でも、海図の正確さを保てるのはそのためです。

$ waypoint refresh
Dashboard refreshed: 3 projects, 1 active this week, 1 attention item, 1 with unlogged sessions, 1 stale, 1 untracked folder.

これは examples/logbook/ にある架空の航海日誌です。海図で各ケースを確認できます。waypoint refresh は chart.html も書き込みます。これはブラウザーで開ける、同じ海図のページです。

はじめに

Python 3.11 以降が必要です。それ以外の依存関係はありません。矢印キーで操作する画面は任意です。waypoint-mcp[tui]（Rich と prompt_toolkit を追加）をインストールして、waypoint を実行してください。

macOS / Linux

pipx install waypoint-mcp         # or: python -m pip install waypoint-mcp
waypoint setup                    # fitting out: logbook, roots, the rule and MCP server for each AI CLI it finds
waypoint add ~/code/my-project    # chart a voyage (project); once per project
waypoint refresh                  # refresh the dashboard: DASHBOARD.md, dashboard.json and chart.html (--open opens it)
waypoint status                   # everything at a glance, with fixes for problems
waypoint archive <project>        # hide a finished project, keep its log (also: restore, remove, ignore)

Windows（PowerShell）

py -m pip install waypoint-mcp
waypoint setup
waypoint add $HOME\code\my-project
waypoint refresh

• waypoint が見つからない場合： インストール先のフォルダーが PATH に含まれていません。AI ツールも waypoint mcp を起動するため、PATH に含める必要があります。pipx でインストールした場合は pipx ensurepath を実行してから、新しいターミナルを開いてください。pip でインストールした場合は、pip が警告した scripts フォルダーを PATH に追加してください。それまでは python -m waypoint …（Windows の場合は py -m waypoint …）を使うと、同じ Python で実行できます。
• 画面（pipx install "waypoint-mcp[tui]"）：waypoint setup では、航海日誌、ルート、プロジェクト、AI ツールを順に設定できます。変更内容をすべてレビュー画面に表示し、適用するまで書き込みません。以降は waypoint だけでプロジェクト（アーカイブ、復元、削除、無視、追跡）やツール（接続、切断、設定のずれの修正）を管理し、状態を確認できます。キー操作：↑↓で移動、Space で切り替え、Enter で次へ、←で戻る、/で検索、Esc で終了します。すべての操作は通常のコマンドでも実行できます。追加機能がない場合や setup にフラグを指定した場合は、番号付きのプロンプトが表示されます。NO_COLOR に対応しています。
• setup は変更するファイルをすべて表示し、確認を 1 回求めます。航海日誌の場所は記憶されるため、以降のコマンドでは --logbook は不要です。ユーザー自身の CLAUDE.md や AGENTS.md のテキストは編集しません。Waypoint 専用のファイルか、マーカー付きのブロックを追加します。waypoint rules --uninstall を実行すると、その部分だけが削除されます。
• 航海日誌をプライベートな git リポジトリにしてから、waypoint refresh --push を実行すると、変更を取得し、海図を再生成し、航海日誌のデータだけをコミットして、プッシュします。
• このリポジトリをクローンした場合：python -m pip install -e .

参加者

自動セッション履歴（どのプロジェクトで、どのツールを、いつ使ったか）を取得できるのは、Claude Code と Codex のみです。他のツールもルールに従って MCP ツールを利用できますが、セッションは自動では表示されません。

ナビゲーター（AI CLI）	ティア	Waypoint が設定するもの
Claude Code	対応済み	ルール、ローカル MCP サーバー、セッション情報
Codex（CLI とデスクトップ）	対応済み	ルール、ローカル MCP サーバー、セッション情報
Gemini CLI	プレビュー	ルール、ローカル MCP サーバー
GitHub Copilot CLI	プレビュー	ルール、ローカル MCP サーバー
Cursor、Windsurf、Kiro、Cline、Claude Desktop、Goose、opencode、Amp	スニペット	waypoint connect <cli> が貼り付け用の設定を表示します。ファイルは書き込みません
ChatGPT	ビーコン	ホストするリモート MCP サーバー（ビーコンを立てる）

• ルールは、意味のある作業の後にログエントリを追加するようツールに指示します。ローカル MCP サーバー（waypoint mcp、stdio）は、5 つのツールを提供します。take_fix（概要）、read_chart（1 つのプロジェクト）、log_watch（ツール固有の ID を使い、ロック下でログエントリを 1 件追加します。done／next が指定されている場合は、Now の Done、Next、Updated も更新します）、status（Waypoint が正しく設定されているかを確認します。状態と件数のみを返し、パスは返しません）、eod_report（本日の終業時メールを生成します。読み取り専用です）。また、3 つのプロンプトも提供します（Claude Code では /mcp__waypoint__<name>、Gemini CLI では /<name> としてスラッシュコマンドになります）。where_am_i、log_this、send_eod です。
• waypoint connect <cli> は、いつでも 1 つの CLI をすべてのプロジェクトに設定します。特定のリポジトリだけに設定するには --project <repo> を追加します（繰り返し指定できます）。ルールはリポジトリに追加され（インポート、ログブックのルールへのリンク、またはコピーしたブロック）、MCP エントリはそのリポジトリに限定されます。Waypoint がそこで作成するファイルは、.git/info/exclude によって Git の対象外になります。waypoint disconnect <cli> [--project <repo>] は、Waypoint が追加したものだけを削除します。
• MCP サーバーは、各 CLI に mcp add コマンドがある場合、そのコマンドを使って登録されます（Codex と Copilot CLI では、リポジトリごとに Waypoint がリポジトリのファイルを編集します）。すでに別のサーバーが waypoint という名前を使っている場合、Waypoint は waypoint-local として登録します。--no-mcp を指定すると、ルールのみをインストールします。Codex では、Waypoint はログブックをサンドボックスの writable_roots に追加することも提案します（--no-writable-root を指定すると追加をスキップします）。
• waypoint rules は、各ツールのルールが同期済み、差分あり、未設定、または別のルールに遮られている（Codex が代わりに AGENTS.override.md を読み込んでいる）ことを報告します。
• 既知の制限事項： Claude Code は、デフォルトでトランスクリプトを 30 日後に削除します。Claude Code と Codex の履歴形式は非公式です。読み取り機能が動作しなくなった場合は、チャートのソースの健全性に表示されます。

プラグイン：リマインドするフック

ルールはエージェントに記録を残すよう求め、プラグインのフックはそれをリマインドします。セッション開始時に、エージェントにはプロジェクトの Now と最新のログエントリーが表示されます。リポジトリが変更され、プロジェクトファイルが変更されていないターンの終了時には、記録を残すよう一度だけ求められます（または、記録することがないと伝えるよう求められます）。フックはリマインドするだけです。エントリーを書くのは引き続きエージェントです。

まず Waypoint をインストールし（pipx install waypoint-mcp を実行して waypoint を PATH に追加します）、waypoint setup --no-mcp を実行します（または waypoint setup の後に waypoint connect <cli> --plugin を実行します。これにより、setup が作成した個別の MCP エントリーが削除されます）。その後、次の手順を実行します。

CLI	インストール
Claude Code	claude plugin marketplace add STiFLeR7/waypoint-mcp を実行し、その後 claude plugin install waypoint@waypoint-mcp を実行します
Codex	codex plugin marketplace add STiFLeR7/waypoint-mcp、codex plugin add waypoint@waypoint-mcp の順に実行し、その後 /hooks でフックを信頼します（アップデートのたびに再度必要です）
Copilot CLI	copilot plugin install STiFLeR7/waypoint-mcp
Gemini CLI	gemini extensions install https://github.com/STiFLeR7/waypoint-mcp

ツール独自の設定に Waypoint のフックを手動で記述している場合は、プラグインのインストール後に一度削除してください。そうしないと、リマインドが二重に実行されることがあります。

--tool auto の場合、フックはプラグインの環境変数（GEMINI_SESSION_ID、COPILOT_PLUGIN_ROOT、PLUGIN_ROOT、CLAUDE_PLUGIN_ROOT）によってツールを判別します。これらをグローバルに設定しないでください。

プラグインには MCP サーバーも含まれているため、waypoint connect <cli> --plugin を実行すると、Waypoint の個別の MCP エントリーが削除されます。waypoint status では、各ツールのフックが最後に実行された時刻を確認できます。waypoint.toml で一部の機能を無効にできます。[hooks] context = false、nudge = false、または quiet = ["project"] を指定します。

1日の終わりにメールを送信する

任意です。1日の終わりに、AI ツールにその日のレポートを送信するよう依頼できます。Claude Code では /mcp__waypoint__send_eod（Waypoint が waypoint-local として登録されている場合は /mcp__waypoint-local__send_eod）、Gemini CLI では /send_eod と入力するか、「send my EoD」と伝えてください。Waypoint はログブック（eod_report）からメールを作成します。ダークテーマでメールに適した HTML ページとプレーンテキスト版が含まれ、Waypoint のマークが添付され、その日に日付が付いたすべてのログエントリーが記載されます。AI ツールは、AgentMail を通じてその内容をそのまま送信します。AgentMail への接続は一度だけで済みます。Waypoint 自体は何も送信せず、受信トレイを見ることもありません。

• waypoint setup ではメールアドレスの入力を求められる場合があります（デフォルトは No、--yes を指定した場合は尋ねません）。または waypoint email --to [email protected] を実行します。アドレスはローカルファイル1つに保存され、waypoint email --forget で削除できます。
• waypoint email を実行すると、見つかった各 AI ツールでの AgentMail の設定手順と、記憶されているアドレスが表示されます。
• ChatGPT：Waypoint beacon と AgentMail の両方のアプリを使えるチャットで「send my EoD」と入力します。1つのチャットで両方のアプリを使えるかどうかは、まだ確認されていません。
• 注意事項の行はメールに含まれません。Waypoint が自動的に除外します。プライバシーを参照してください。

チャートの見方

チャート上の表示	意味
航海：航行中／惰性航行中／停泊中／入港	プロジェクト：進行中／時々利用／一時停止／完了
危険要因	- Attention: の行に加え、変更されているルールと読み取れないソース
未記録の当直	プロジェクトの最新ログエントリーの日付より後に行われた AI セッション
ログより古い Now	## Now が最新のログエントリーより前に更新された
漂流中	しきい値を超えてアイドル状態（進行中なら21日、時々利用なら60日）
未踏の海域	最近 AI の利用があったものの、プロジェクトファイルがないフォルダー
港	projects/_archive/：完了した航海を保管する場所。削除されることはありません

Waypoint がプロジェクトのステータスを変更したり、アーカイブしたり、自らログエントリーを書いたりすることはありません。問題を通知し、判断するのはあなたです。

シグナルの意味

• Activity は、ツールがプロジェクトに触れたこと（セッション、コミット、ログエントリ）を意味します。作業が完了したという意味ではありません。
• Unlogged sessions は、最新のログエントリの翌日以降の Claude Code と Codex のセッションです。ログエントリには日付のみが記録され、時刻は記録されません。そのため、エントリと同じ日の後の作業はログ済みとして扱われます。
• Now behind log は、プロジェクトの ## Now が最新のログエントリより前に最終更新されている（- Updated: の日付が前である）ことを意味するため、中断した箇所 と 次にすること が古くなっている可能性があります。Updated 行のないプロジェクトには表示されません。done／next を渡すと、log_watch がこの行を設定します。
• ログエントリ は、誰かが書き留めた内容を記録します。コードの正しさを検証するものではありません。
• 利用可能なコンテキスト は、エージェントがそれを読んだ証拠ではありません。
• 鮮度： chart.html と DASHBOARD.md は、最後に waypoint refresh を実行した時点のスナップショットです。ローカル MCP サーバーはログブックをリアルタイムで読み込みます（AI アクティビティは最大30秒間キャッシュされます）。ビーコンのダッシュボード項目は最後にプッシュした時点の情報です。ログエントリはリアルタイムで読み込まれます。

プライバシー

• 何も自動的にマシンの外へ送信されません。 エンジンはリスナーを持たず、ネットワークリクエストを送信せず、テレメトリーも収集しません。--push は、設定したリモートに対して git を実行します。
• ローカル MCP サーバーは、起動した AI ツールにのみ応答します。 そのツールは、読み取ったほかの情報と同様に、結果をモデルプロバイダーへ送信します。結果には、プロジェクト名、ステータス、Summary、Done、Next、および最近のログエントリが含まれます。waypoint.toml で [mcp] include_attention = true を設定しない限り、Attention 行は除外されます。セッションタイトル、ファイルパス、未追跡フォルダー、フィードは返されません。
• 1日の終わりのメールは、ユーザーが依頼したときに限り、AI ツールが AgentMail（サードパーティ）を通じて送信します。メールアドレスは1つのローカルファイルに保存され、send_eod を実行するツールにのみ渡されます。詳細：docs/PRIVACY.md。
• ログのテキストは自由記述です。あなたやツールがそこに書き込んだ内容は、結果が送られる先に送信されます。返されるテキストはツール用のデータであり、指示ではありません。

3つの船体

船体	内容	場所
エンジン	このリポジトリ：仕様、waypoint CLI、テンプレート、テスト	PyPI からインストール
ログブック	あなたのデータ：プロジェクトごとの Markdown ファイルとチャート	専用のプライベート git リポジトリ
プレイグラウンド	実験とプロトタイプ	任意の場所

これらが混ざることはありません。エンジンは配布され、ログブックはあなたの手元に残ります。

ビーコンを立てる

ChatGPT はローカル履歴を保持せず、ローカルサーバーを起動できません。ビーコン（beacon/、上級者向け）は、GitHub OAuth の背後で Cloudflare Workers 上にホストするリモート MCP サーバーで、あなたの GitHub アカウントからのリクエストにのみ応答します。take_fix と read_chart はチャートを読み込み、show_chart は ChatGPT と Claude 内にカードとしてチャートを表示します（MCP Apps）。log_watch は chatgpt のログエントリを1件、ログブックのリポジトリに追加します。セットアップには Cloudflare アカウント、GitHub OAuth アプリ、きめ細かなトークンが必要です：beacon/README.md。ビーコンを使わない場合は、ChatGPT の要約をプロジェクトファイルに chatgpt エントリとして貼り付けてください。

仕様

ログブックの形式、ルール、チャートの JSON、すべてのアクセス契約は docs/LOGBOOK-SPEC.md（v1.5）に記載されています。ストーリーの用語集と語り口は docs/STORY.md に記載されています。

開発

python -m unittest                # stdlib only (the screen's tests skip)
python -m pip install -e ".[tui]" && python -m unittest   # with the screen's tests
python examples/build.py --check  # the example chart (Linux or macOS)
cd beacon && npm test             # the beacon

設計上の決定は docs/decisions/ に、リリース計画は docs/release/R0-SCOPE.md に記載されています。