claude-checkpoint-mcp

session-checkpoint-mcp

Claude Code のセッション状態をローカルに保存するため、クラッシュや/clear、コンテキスト上限が発生しても、Claude がコンテキストを最初から再構築する必要はありません。

session-checkpoint-mcpは、次の3つのツールを備えたローカルのModel Context Protocolサーバーです。

• save_session_checkpointは、セッションの作業状態をプロジェクト内の小さなJSONファイルに書き込みます。
• load_session_checkpointは、そのファイルを簡潔な再開用ブリーフに変換します。
• list_session_checkpointsは、プロジェクト内のチェックポイントを一覧表示し、再開するセッションを選べるようにします。

各Claude Codeセッションには専用のチェックポイントが作成されるため、複数のセッションで同じディレクトリを共有しても、互いに上書きされません。

すべての処理はお使いのマシン上で実行されます。データが外部に送信されることはありません。

Tenzinによるtenlean/claude-checkpoint-mcpのフォークです。リポジトリ名は元の名称のままです。サーバーはsession-checkpoint-mcpとして公開され、Claude Code プラグインはsession-checkpointです。

---

目次

• 理由：同じコンテキストに二度コストをかけない
• 仕組み
• インストール
• 設定
  • 環境変数
  • Claude Code
  • セッション開始時の通知
  • サブエージェントの保存ガード
  • Claude Desktop
  • その他のMCPクライアント
• 使い方
• ツールのリファレンスと例
• チェックポイントファイル
• 互換性
• セキュリティとプライバシー
• トラブルシューティング
• 開発

---

理由：同じコンテキストに二度お金を払うのをやめる

Claude Code の長いセッションでは、多くのコンテキストが蓄積されます。

• 何をしようとしているのか。
• どのアプローチがすでに失敗したのか。
• どのファイルが重要なのか。
• まだ失敗しているテストはどれか。

作業の途中で、いくつかのことがそのコンテキストを消し去る可能性があります。

• ターミナルのクラッシュ、SSH の切断、またはノート PC のスリープ。
• コンテキストウィンドウの上限に達すること。
• 新しいウィンドウを開くための /clear。

次のセッションは、何も知らない状態から始まります。元の状態に戻るには、Claude がそのコンテキストを再構築しなければなりません。

• ファイルを読み直すことで、何が、なぜ変更されたのかを把握します。ファイルを読むたびに入力トークンが発生します。
• 探索をやり直すこと。状態を再発見するためだけに、grep、git diff、ls、テストの実行などを行います。
• 再説明すること。目標、制約、行き詰まった点を入力し直すか、Claude が苦労して行き詰まった点を再発見します。

これらのやり取りのたびに、増え続ける会話が入力として再送されるため、コストが積み重なります。

session-checkpoint-mcp は、この再構築を小さく構造化された読み込みに置き換えます。

	チェックポイントがない場合	load_session_checkpoint を使う場合
目標と制約の復元	入力し直すか、Claude が推測します	ブリーフの 1 セクション
完了済みと保留中の把握	コードと git から再導出します	ステータス付きのタスクリスト
重要なファイルの把握	広範囲に読み直します	メモ付きの、変更したファイルの正確な一覧
その後に何が変わったかの把握	念のためすべて読み直します	実際に内容が変わったファイルのみが通知されます
失敗した試行の記憶	繰り返されることが多いです	決定事項と注意点 に記録されます

一般的なセッションの再開ブリーフは約 1.2 KB の Markdown で、トークン数は数百程度です。以下の例は、そのサイズの実際の出力です。

最も大きな節約につながるのは、差分の検出です。保存時に、サーバーは未コミットの変更があるファイルごとにコンテンツハッシュを記録します。読み込み時には、そのハッシュを作業ツリーと比較し、チェックポイントの作成後に変更されたファイルを Claude に正確に伝えます。ブリーフ内のそれ以外の情報はそのまま信頼できるため、Claude は必要なものだけを読み直します。

---

仕組み

  Session 1                                     Session 2 (after crash / /clear)
  ─────────                                     ────────────────────────────────
  Claude ──save_session_checkpoint──┐       ┌──load_session_checkpoint── Claude
         goal, tasks, summary,      │       │   compact markdown brief
         next steps, decisions,     ▼       │   + "changed since checkpoint"
         files, commands      ┌─────────────────────┐
                              │ <project>/          │
     server adds:             │ .claude-checkpoint  │◀── git: branch, HEAD,
     git branch/HEAD,         │ .claude-checkpoint  │    dirty files + hashes
     dirty files + hashes,    │   .prev (backup)    │
     redacts secrets          └─────────────────────┘

• 意味を提供するのは Claude です：目標、進捗、決定事項、次のステップ、重要なコマンドを提供します。
• 事実を提供するのはサーバーです：git のブランチと HEAD、コンテンツハッシュを含む、未コミットまたは未追跡のすべてのファイル、そしてタイムスタンプを提供します。
• サーバーの指示により、Claude はいつ行動すべきかを把握できます。 Claude は、セッションの開始時に読み込み、節目の後、リスクのある操作の前、会話が長くなったときに保存するよう指示されます。毎回プロンプトを与える必要はありません。
• プラグインのセッション開始フックにより、再開の信頼性が高まります。 セッションの開始時に、エージェントがサーバーの指示を見落とすのは簡単です。Claude Code プラグインをインストールすると、SessionStart フックもチェックポイントの有無を確認し、存在する場合は、Claude にその読み込みを促し、内容に基づいて行動する前に確認するよう指示します。

セッションごとに1つのチェックポイント

Claude Code は各 MCP サーバーにセッション ID（CLAUDE_CODE_SESSION_ID）を渡します。サーバーはこれを使って、各セッション専用のファイル <project>/.claude-checkpoints/<session-id>.json を用意します。これにより、同じディレクトリ（/tmp や claude agents の実行場所など）を共有するセッション同士で、互いの内容を上書きしたり統合したりすることがありません。

• 保存では、常に現在のセッション専用のファイルに書き込みます。
• 読み込みでは、現在のセッションのチェックポイントがあれば、それを返します。なければ、ほかのチェックポイントが存在する場合に、その一覧（目標、最終保存時刻、ブランチ、すべてのタスクが完了しているかどうか）を返し、Claude がどれを再開するか尋ねます。候補が1つだけの場合も含め、Claude が自動で選ぶことはありません。
• 別のセッションのチェックポイントを再開すると、そのチェックポイントを読み込みますが、保存先は引き続き現在のセッション専用ファイルです。読み込み結果は、次の保存時に Claude がそのチェックポイントのセレクターを resumedFrom として渡すよう指示します。これにより、保存時に再開したチェックポイントを起点とし、どこから再開したかを記録します。サーバーはこれをメモリに保持しないため、間にサーバーが再起動しても機能します。元のチェックポイントが変更されることはありません。
• チェックポイントは削除するまで保持されるため、古いセッションを後から再開できます。
• セッション ID のないクライアント（例：Claude Desktop）にも、会話ごとにチェックポイントが用意されます。最初の保存時にセッション ID が生成され、.claude-checkpoints/<id>.json に書き込まれ、その ID が返されます。Claude は、その会話で以降のすべての呼び出しに session として ID を渡します（たとえばコンパクション後に）Claude が ID を失った場合、次の保存では新しいチェックポイントが作成されます。既存のチェックポイントに書き込まれることはありません。ID なしで読み込むと、チェックポイントの一覧が表示され、新しい Claude Code セッションと同様に、再開するものを選べます。テストでは（#42）、Opus、Sonnet、Haiku はコンパクション後も含め、保存のたびに ID を返しました。
• 共有の .claude-checkpoint ファイルは、1.0 より前にセッション ID のないクライアントが使用していたファイルです。この動作を維持するには、CHECKPOINT_SESSION_IDS を legacy に設定します。ID なしの保存はすべてそのファイルに書き込まれ、ID なしの読み込みではそのファイルが直接開かれます。どちらの場合も、以前のバージョンが残した .claude-checkpoint は一覧に legacy として表示されます。この設定は Claude Code には影響しません。Claude Code では、常に独自のセッション ID が優先されます。

どのクライアントも session を明示的に渡せます。Claude Code では、セッション独自の ID と一致している必要があります。異なる ID を渡すとエラーになります。これは、通常、チェックポイントのセレクターを誤った引数に渡したことを意味するためです（チェックポイントを読み込むには checkpoint を、そこから再開するには resumedFrom を使ってください）。

MCP サーバーが認識するセッション ID は、サーバーの起動時に渡されたものです。

操作…	サーバーが認識する内容	結果
新しい claude を起動する（例：クラッシュ後）	新しい ID	一覧が表示され、再開するものを選べます
/clear を実行する	クリア前と同じ ID	クリア前のチェックポイントが直接読み込まれ、その後の保存で更新されます
claude --resume <id> を実行する	その ID	そのセッションのチェックポイントが直接読み込まれます
claude --continue、または ID を指定せずに --resume を実行する	別の ID になる場合があります	一覧が表示されます

---

インストール

要件：Node.js 20 以降と git。git は任意ですが、ない場合は差分検出を利用できません。

git clone https://github.com/daniel-munoz/claude-checkpoint-mcp.git
cd claude-checkpoint-mcp
npm install
npm run build

サーバーのエントリーポイントは dist/index.js に移動しました。

npm からインストール。 サーバーは session-checkpoint-mcp としても公開されています。以下のどの設定でも、node /absolute/path/to/claude-checkpoint-mcp/dist/index.js を npx -y session-checkpoint-mcp に置き換えられます。

claude mcp add --scope user checkpoint -- npx -y session-checkpoint-mcp

（npm パッケージ claude-checkpoint-mcp は、このフォークではなく、上流プロジェクトの 0.1.0 リリースです。）

---

設定

環境変数

変数	設定者	必須	デフォルト	説明
CHECKPOINT_PROJECT_ROOT	あなた（任意）	いいえ	未設定の場合：クライアントのルート、次にサーバーの作業ディレクトリ	チェックポイントの対象となるデフォルトのプロジェクトの絶対パスです。Claude Desktop など、現在のプロジェクトがないクライアントで使用します。ツール呼び出し時の projectRoot 引数が優先されます。
SESSION_CHECKPOINT_NUDGE	あなた（任意）	いいえ	未設定の場合：ナッジはオン	off（または 0、false、no）に設定すると、プラグインのセッション開始時のナッジがオフになります。サーバーではなくフックによって読み取られます。
CLAUDE_CODE_SESSION_ID	Claude Code（自動）	いいえ	未設定の場合：会話ごとにセッション ID が生成されます（CHECKPOINT_SESSION_IDS を参照）	このセッションのチェックポイントファイル .claude-checkpoints/<session-id>.json を選択します。自分で設定する必要はありません。セッションごとに 1 つのチェックポイントを参照してください。
CHECKPOINT_SESSION_IDS	あなた（任意）	いいえ	未設定（mint と同じ）：セッション ID のないクライアントには会話ごとに専用のチェックポイントが作成されます	legacy に設定すると、セッション ID のないクライアントが以前の 1.0 より前のバージョンと同様に、1 つの .claude-checkpoint ファイルを共有します。それ以外の値は警告とともに mint にフォールバックします。独自のセッション ID が優先される Claude Code には影響しません。セッションごとに 1 つのチェックポイントを参照してください。

Claude Code

プラグインとして使用（最も簡単）。 このリポジトリは Claude Code のプラグインマーケットプレイスでもあります。クローンやビルドは不要です。

claude plugin marketplace add daniel-munoz/claude-checkpoint-mcp
claude plugin install session-checkpoint@daniel-munoz

Claude Code を再起動すると、/mcp に plugin:session-checkpoint:session-checkpoint が接続済みとして表示されます。

0.2.x 以前からアップグレードする場合　Claude Code が claude- プレフィックスを独自のプラグイン用に予約しているため、0.3.0 でプラグインの名前が claude-checkpoint-mcp から session-checkpoint に変更されました。古いプラグインをアンインストールして、新しいプラグインをインストールしてください。

claude plugin uninstall claude-checkpoint-mcp@daniel-munoz
claude plugin marketplace update daniel-munoz
claude plugin install session-checkpoint@daniel-munoz

ツールの完全名が mcp__plugin_claude-checkpoint-mcp_claude-checkpoint__* から mcp__plugin_session-checkpoint_session-checkpoint__* に変更されました。古い名前を使用している settings.json、フック、手順書内の権限許可リストを更新してください。save_session_checkpoint などの短縮名や既存のチェックポイントファイルには影響しません。

手動でセットアップする場合。 リポジトリをクローンした場合は、ユーザーアカウントにサーバーを一度登録すると、すべてのプロジェクトで利用できるようになります。

# Run from the claude-checkpoint-mcp directory
claude mcp add --scope user checkpoint -- node "$PWD/dist/index.js"

絶対パスを使用してください。 ユーザー単位のサーバーは、Claude Code を開いたプロジェクトから起動します。./dist/index.js のような相対パスは、このリポジトリではなく、そのプロジェクトを基準に解決されます。コマンドの実行時に "$PWD/dist/index.js" が絶対パスに展開され、そのパスが保存されます。

登録されていることを確認します。

claude mcp list

セッション中に /mcp を実行すると、checkpoint が接続済みとして表示されます。

プロジェクト単位で設定する方法。 バージョン管理を通じてサーバーをチームで共有するには、プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "checkpoint": {
      "command": "node",
      "args": ["/absolute/path/to/claude-checkpoint-mcp/dist/index.js"]
    }
  }
}

いずれの場合も、チェックポイントファイルをプロジェクトの .gitignore またはグローバルの gitignore に追加してください。

.claude-checkpoint*

セッション開始時の通知

このプラグインには SessionStart フックが付属しています（plugin/hooks/hooks.json、node dist/hook.js を実行）。セッションの開始時、再開時、クリア時、または圧縮時に実行されます。プロジェクトにチェックポイントがある場合、Claude のコンテキストにメモを追加します。メモには、チェックポイントの数、最新のチェックポイントが保存された日時、記録された内容に基づいて行動する前に load_session_checkpoint を呼び出し、あなたに確認するよう指示する内容が含まれます。チェックポイントがない場合は何も出力しません。必要なのは Node のみです。サーバーでもすでに必要なため、macOS、Linux、Windows で動作します。

サーバーが使うものと同じプロジェクトルートを参照します（プロジェクトルートの選択方法）。フックの環境で CHECKPOINT_PROJECT_ROOT が設定されていればその値を使い、そうでなければ Claude Code の起動ディレクトリを使います。これは git の最上位ディレクトリではないため、Claude をサブディレクトリで起動すると、そのサブディレクトリから保存されたチェックポイントのみが報告されます。これは通常の load_session_checkpoint で見つかるものと同じです。CHECKPOINT_PROJECT_ROOT を MCP サーバーの設定だけで指定する場合は、フックから参照できるように settings.json の env にも設定してください。

無効にする方法。 settings.json の env ブロックで SESSION_CHECKPOINT_NUDGE を off に設定します。

{ "env": { "SESSION_CHECKPOINT_NUDGE": "off" } }

手動セットアップ（claude mcp add）ではフックはインストールされません。プラグインを使わずに通知を有効にするには、settings.json で node /absolute/path/to/claude-checkpoint-mcp/dist/hook.js を SessionStart コマンドフックとして登録してください。

独自の通知フックを使っていて、0.3.x からアップグレードする場合：設定に checkpoint-nudge.sh フックをコピーしていた場合（例：~/.claude/hooks/checkpoint-nudge.sh）、通知が二重に表示されるようになります。そのスクリプトを削除し、settings.json から SessionStart のエントリーも削除してください。~/.claude や CLAUDE_CONFIG_DIR の各プロファイルなど、使用するすべての設定ディレクトリで行ってください。

サブエージェントの保存ガード

サブエージェントは親セッション内で実行され、その MCP サーバーを共有するため、セッション ID も共有します。ガードがないと、サブエージェントが save_session_checkpoint を呼び出した際に親のチェックポイントを上書きしてしまいます。また、mode: "replace" の場合は、サブエージェント自身の限定的なサブタスクだけが残ることになります。

このプラグインには、このための PreToolUse フックが付属しています（plugin/hooks/hooks.json、node dist/guard.js を実行し、^mcp__.+__save_session_checkpoint$ に一致）。呼び出し元がサブエージェントの場合、保存を拒否し、代わりに進捗を親エージェントに報告するよう指示します。メインセッションからの保存、およびすべての読み込みと一覧表示の呼び出しは、そのまま実行されます。フックを利用できないクライアント向けに、サーバーの指示と保存ツールの説明にも同じ内容が記載されています。

サブエージェントの判定には、サブエージェント内で Claude Code がフック入力に追加する agent_id フィールドを使用します（Claude Code 2.1.322 で確認済み）。--agent を付けて開始したメインセッションにも存在するため、agent_type のみでは判定しません。agent_id を送信しないバージョンの Claude Code を使っている場合や、何らかの理由でフックが失敗した場合は、保存が実行されます。そのため、このフックがメインセッションをブロックすることはありません。

手動セットアップ（claude mcp add）では、このフックはインストールされません。プラグインを使わずに追加するには、settings.json で node /absolute/path/to/claude-checkpoint-mcp/dist/guard.js を、上記のマッチャーを指定した PreToolUse コマンドフックとして登録してください。

Claude Desktop（claude_desktop_config.json）

設定ファイルを開きます。

OS	パス
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

ローカルビルドへの絶対パスを指定して、mcpServers の下にサーバーを追加します。

{
  "mcpServers": {
    "checkpoint": {
      "command": "node",
      "args": ["/absolute/path/to/claude-checkpoint-mcp/dist/index.js"],
      "env": {
        "CHECKPOINT_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

ファイルを保存した後、Claude Desktop を再起動してください。

Claude Desktop には「現在のプロジェクト」という概念がありません。CHECKPOINT_PROJECT_ROOT を使ってデフォルトのプロジェクトを設定するか、呼び出しごとに Claude から projectRoot を渡してください（「/home/me/code/my-app のチェックポイントを保存して」）。プロジェクトルートの解決を参照してください。

その他の MCP クライアント

stdio トランスポートに対応する MCP クライアントであれば、どれでもサーバーを実行できます。

node /absolute/path/to/claude-checkpoint-mcp/dist/index.js
# or
npx -y session-checkpoint-mcp

---

使い方

サーバーに組み込まれた指示で、一般的なケースは自動的に処理されます。Claude に直接依頼することもできます。

保存：

• 「進捗をチェックポイントとして保存してください。」
• 「マイグレーションを実行する前にチェックポイントを保存してください。」
• 「チェックポイントを更新してください。今行った作業を統合してください。」

再開（新しいセッションで）：

• 「前回の続きから再開してください。」
• 「チェックポイントを読み込んで続けてください。」

再開時の概要の例

これは load_session_checkpoint の実際の出力です。このシナリオでは、保存後に1つのファイルが変更されないままコミットされ、その後、チームメイトが session.ts を編集しました。

# Resuming: my-app (checkpoint saved 2m ago, 2026-10-08 02:23:55 UTC)
Branch `feat/github-oauth` @ b2ef1b591 (uncommitted changes)

## Goal
Add GitHub OAuth login with persistent sessions

## Tasks
- [x] OAuth callback route
- [~] Session cookie persistence
- [ ] Logout endpoint

## Where things stand
Callback exchanges the code and creates a session, but the cookie is dropped on reload. Suspect SameSite/secure flags in dev.

## Next steps
1. Set sameSite: 'lax' and secure only in production in src/auth/session.ts
2. Re-run npm test -- auth
3. Start the logout endpoint

## Decisions & gotchas
- Use iron-session, not express-session (needs edge runtime support)
- Don't mock the GitHub API in e2e tests; use the recorded fixtures in test/fixtures

## Files touched (3)
- src/auth/session.ts (M) — cookie options
- src/auth/callback.ts (M)
- src/auth/session.spec.ts (??)

## Recent commands (last 2, oldest first)
- ✓ `GITHUB_CLIENT_SECRET=«redacted» npm run dev`
- ✗ exit 1 `npm test -- auth` — 2 failing in session.spec.ts: cookie missing after reload

## Since this checkpoint
- 1 new commit(s) on HEAD
- ⚠ Changed after the checkpoint, re-read before editing: `src/auth/session.ts`

callback.ts は保存後にコミットされましたが、内容に変更がなかったため、フラグは付いていません。再度読み込む必要があるのは session.ts だけです。

タスクマーカー：[x] 完了 · [~] 進行中 · [ ] 未着手 · [!] ブロック中。

---

ツールのリファレンスと例

save_session_checkpoint

現在のセッションのチェックポイントを <projectRoot>/.claude-checkpoints/<session-id>.json に書き込みます。セッション ID のないクライアントには、初回保存時に ID が発行されます（または、CHECKPOINT_SESSION_IDS=legacy の場合は <projectRoot>/.claude-checkpoint に書き込みます）。

パラメーター	型	必須	説明
goal	string (≤ 500)	✅	セッションの主な目標
tasks	{ description, status }[] (≤ 30)		status：pending · in_progress · done · blocked
summary	string (≤ 4000)		現状：機能していること、壊れていること、作業の途中だった内容
nextSteps	string[] (≤ 20)		再開する人が行う次のアクション（順序付き）
decisions	string[] (≤ 20)		重要な決定事項、制約、避けるべき行き詰まり
modifiedFiles	{ path, note? }[] (≤ 100)		注記を付けるファイル、または含めるコミット済みファイル。未コミットの git 変更は自動的に検出されます。プロジェクト内の絶対パスは相対パスとして保存されます。
recentCommands	{ command, exitCode?, note? }[] (≤ 50)		重要なコマンド（古いものから順）。シークレットは伏せられます。
mode	"replace" | "merge"		デフォルトは replace です。詳細は以下を参照してください。
resumedFrom	string		このセッションの再開元となったチェックポイントのセレクターです。別のセッションのチェックポイントを読み込んだ後、最初に保存するときに渡します。merge 保存ではその内容を引き継ぎ、どちらのモードでも記録されます。セッション独自のチェックポイントができた後は無視されます。不正な形式のセレクターはツールエラーになります。存在しない、または読み込めない場合は警告が表示され、チェックポイントなしで保存が続行されます。
session	string		以前の保存で返された、この会話のセッション ID です。セッション ID を提供する Claude Code では省略します。指定する場合は、一致している必要があります。チェックポイントを読み込むための選択には使いません。読み込む対象は checkpoint で指定します。
projectRoot	string (absolute)		ルートの決定方法を上書きします

全体保存：

{
  "goal": "Add GitHub OAuth login with persistent sessions",
  "tasks": [
    { "description": "OAuth callback route", "status": "done" },
    { "description": "Session cookie persistence", "status": "in_progress" },
    { "description": "Logout endpoint", "status": "pending" }
  ],
  "summary": "Callback exchanges the code and creates a session, but the cookie is dropped on reload. Suspect SameSite/secure flags in dev.",
  "nextSteps": [
    "Set sameSite: 'lax' and secure only in production in src/auth/session.ts",
    "Re-run npm test -- auth"
  ],
  "decisions": ["Use iron-session, not express-session (needs edge runtime support)"],
  "modifiedFiles": [{ "path": "src/auth/session.ts", "note": "cookie options" }],
  "recentCommands": [
    { "command": "GITHUB_CLIENT_SECRET=gh_live_8f2a91 npm run dev", "exitCode": 0 },
    { "command": "npm test -- auth", "exitCode": 1, "note": "2 failing in session.spec.ts" }
  ]
}

応答（モデルに表示されるテキスト）：

Checkpoint saved to /home/me/code/my-app/.claude-checkpoint (2202 bytes, replace).
3 task(s), 3 file(s), 2 command(s) on feat/github-oauth@b2ef1b591.
⚠ Redacted 1 secret-looking value(s).

merge による増分更新：

{
  "goal": "Add GitHub OAuth login with persistent sessions",
  "mode": "merge",
  "tasks": [
    { "description": "Session cookie persistence", "status": "done" },
    { "description": "Logout endpoint", "status": "in_progress" }
  ],
  "recentCommands": [{ "command": "npm test -- auth", "exitCode": 0, "note": "all green" }]
}

フィールド	replace	merge
goal	設定	設定
tasks	設定	description の一致に基づいて更新。新しいタスクは追加
summary, nextSteps	設定	指定された場合は置き換え、指定されない場合は保持
decisions	設定	追加（重複は除外）
recentCommands	設定	追加。50件を超える場合は古いものから削除
modifiedFiles	git を新たにスキャンした結果 + 指定分	git を新たにスキャンした結果 + 指定分 + 以前に記録された分
id, createdAt	新規	保持

構造化出力（structuredContent）：

{
  "path": "/home/me/code/my-app/.claude-checkpoint",
  "bytes": 2202,
  "mode": "replace",
  "counts": { "tasks": 3, "modifiedFiles": 3, "recentCommands": 2, "redactions": 1 },
  "warnings": ["Redacted 1 secret-looking value(s)."]
}

セッション ID を使って保存した場合、出力には session（ID）と sessionSource も含まれます。sessionSource は env（Claude Code の CLAUDE_CODE_SESSION_ID）、argument（session として渡された値）、または minted（新規発行。詳細は CHECKPOINT_SESSION_IDS=mint）のいずれかです。argument と minted の場合、以降の呼び出しでも ID を渡すよう Claude に指示するテキストも含まれます。保存先が .claude-checkpoint の場合、これらのフィールドは省略されます。

load_session_checkpoint

読み取り専用です。チェックポイントを読み込み、差分を確認して概要を返します。

パラメーター	型	必須	説明
format	"brief" | "full"		デフォルトは brief です（Markdown。上記の 例 を参照）。full は、差分を含むチェックポイントの完全な JSON を返します。
checkpoint	string		読み込むチェックポイントです。list_session_checkpoints のセレクター（セッション ID または legacy）を指定します。省略すると、現在のセッションのチェックポイントを読み込みます。
session	string		以前の保存時に返された、この会話のセッション ID です。セッション ID が自動的に指定される Claude Code では省略してください。Claude Code で指定する場合は、一致している必要があります。読み込むチェックポイントの選択には使用しません。その場合は checkpoint を指定してください。
projectRoot	string（絶対パス）		ルートの解決方法を上書きします。

例：

{}

{ "format": "full", "projectRoot": "/home/me/code/my-app" }

構造化出力（structuredContent）：

{
  "found": true,
  "path": "/home/me/code/my-app/.claude-checkpoint",
  "fromBackup": false,
  "updatedAt": "2026-10-08T02:23:55.477Z",
  "drift": {
    "branchChanged": false,
    "currentBranch": "feat/github-oauth",
    "commitsSince": 1,
    "changedSince": ["src/auth/session.ts"]
  },
  "warnings": []
}

チェックポイントが存在しない場合、ツールは found: false と「再開するものがありません」というメッセージを返します。これはエラーとして扱われません。

現在のセッションにチェックポイントがなく、ほかのチェックポイントが存在する場合、ツールは found: false とともに candidates（list_session_checkpoints と同じエントリー。新しい順で最大 10 件）、total、omitted、およびどのチェックポイントから再開するかを尋ねるよう Claude に伝える text を返します。不明な checkpoint セレクターを指定すると、ツールエラーになります。

現在のセッション以外のチェックポイントを読み込むと、resumeHint が追加されます。これは概要の先頭行にも表示され、Claude に次回の保存時に resumedFrom を渡すよう伝えます。

list_session_checkpoints

読み取り専用です。プロジェクトのチェックポイントを新しい順に一覧表示します。読み取りできないチェックポイントは非表示にせず、警告とともに最後に表示します。

パラメーター	型	必須	説明
limit	integer ≥ 0		デフォルトは 10 です。0 を指定すると、すべて表示します。
session	string		以前の保存時に返された、この会話のセッション ID です。セッション ID が自動的に指定される Claude Code では省略してください。Claude Code で指定する場合は、一致している必要があります。読み込むチェックポイントの選択には使用しません。その場合は checkpoint を指定してください。
projectRoot	string（絶対パス）		ルートの解決方法を上書きします。

構造化出力（structuredContent、抜粋）：

{
  "path": "/home/me/scratch",
  "entries": [
    {
      "selector": "8ce2c093-d512-42c2-a4d8-aa98280b55df",
      "goal": "Investigate the flaky upload test",
      "updatedAt": "2026-10-19T21:40:23.000Z",
      "age": "2h ago",
      "branch": null,
      "allTasksDone": false,
      "isCurrentSession": false,
      "fromBackup": false
    },
    { "selector": "legacy", "goal": "Quick CSV analysis", "...": "..." }
  ],
  "total": 2,
  "omitted": 0,
  "warnings": [],
  "text": "2 checkpoint(s) in /home/me/scratch, newest first: …"
}

プロジェクトルートの選択方法

1. projectRoot 引数
2. CHECKPOINT_PROJECT_ROOT 環境変数
3. クライアントが MCP ルートをサポートしている場合、クライアントの最初の file:// ルート
4. サーバープロセスの作業ディレクトリ

パスは絶対パスで、既存のディレクトリである必要があります。シンボリックリンクは解決されます。チェックポイントは必ずそのルートの直下に書き込まれます。<root>/.claude-checkpoints/<session-id>.json、または CHECKPOINT_SESSION_IDS=legacy でセッション ID がない場合は <root>/.claude-checkpoint です。

---

チェックポイントファイル

<project>/
├── .claude-checkpoint              # legacy single checkpoint (0.x clients without a session id, CHECKPOINT_SESSION_IDS=legacy, or 0.1.x)
├── .claude-checkpoint.prev         # its backup
└── .claude-checkpoints/            # one checkpoint per session or minted conversation (directory mode 0700)
    ├── <session-id>.json
    └── <session-id>.json.prev      # each with its own backup

すべてのファイルは、モード 0600 でアトミックに書き込まれます。.claude-checkpoint* の gitignore パターンですべてのファイルが対象になります。

各ファイルは、読み取り、差分の確認、手動編集が容易な、バージョン管理されたプレーンな JSON です。実際の例：

{
  "version": 1,
  "id": "ee5507c0-855e-44a5-85c1-d97b767537c9",
  "createdAt": "2026-10-08T02:23:55.477Z",
  "updatedAt": "2026-10-08T02:23:55.477Z",
  "generator": { "name": "session-checkpoint-mcp", "version": "1.0.0" },
  "project": { "name": "my-app" },
  "git": {
    "branch": "feat/github-oauth",
    "head": "b2ef1b5919ee5d456ea146c9362a7abc92b1e556",
    "dirty": true
  },
  "goal": {
    "primary": "Add GitHub OAuth login with persistent sessions",
    "tasks": [
      { "description": "OAuth callback route", "status": "done" },
      { "description": "Session cookie persistence", "status": "in_progress" },
      { "description": "Logout endpoint", "status": "pending" }
    ]
  },
  "summary": "Callback exchanges the code and creates a session, but the cookie is dropped on reload. Suspect SameSite/secure flags in dev.",
  "nextSteps": [
    "Set sameSite: 'lax' and secure only in production in src/auth/session.ts",
    "Re-run npm test -- auth",
    "Start the logout endpoint"
  ],
  "decisions": [
    "Use iron-session, not express-session (needs edge runtime support)",
    "Don't mock the GitHub API in e2e tests; use the recorded fixtures in test/fixtures"
  ],
  "modifiedFiles": [
    { "path": "src/auth/session.ts", "status": "M", "source": "git", "note": "cookie options", "hash": "9ec893ef673dac860e7e2b6fcaad602983eeb0b1" },
    { "path": "src/auth/callback.ts", "status": "M", "source": "git", "hash": "f3ecc849c3875d4f11bb42ae0e5ab6c71931d7f1" },
    { "path": "src/auth/session.spec.ts", "status": "??", "source": "git", "hash": "9daeafb9864cf43055ae93beb0afd6c7d144bfa4" }
  ],
  "recentCommands": [
    { "command": "GITHUB_CLIENT_SECRET=«redacted» npm run dev", "exitCode": 0, "at": "2026-10-08T02:23:55.477Z" },
    { "command": "npm test -- auth", "exitCode": 1, "note": "2 failing in session.spec.ts: cookie missing after reload", "at": "2026-10-08T02:23:55.477Z" }
  ],
  "meta": { "redactions": 1, "truncated": false }
}

フィールド	備考
version	スキーマのバージョンです。不明なバージョンは拒否されます。今後のバージョンでは、読み込み時に古いファイルが移行されます。
id / createdAt	merge 保存では維持され、replace 保存では新しくなります。
sessionId	チェックポイントを所有する Claude Code セッション（レガシーファイルでは存在しません）
resumedFrom	このチェックポイントの開始元となったチェックポイントのセレクター（存在する場合）。以降の保存でも保持されます。
git	Git リポジトリの外部、またはリポジトリの最初のコミット前は null です。
modifiedFiles[].status	Git porcelain コード（M、A、D、R、??）、または Claude のみが報告したファイルの場合は M
modifiedFiles[].source	git（検出されたもの）または agent（Claude が報告したもの、または以前のマージから引き継がれたもの）
modifiedFiles[].hash	保存時点の作業ツリーの内容を示す Git blob ハッシュです。差分の検出に使用されます。
meta.truncated	リストやサイズの上限に収めるために何かが削除された場合は true です。

パスは常にプロジェクトルートからの相対パスです。ファイルに絶対パスが保存されることはありません。

---

互換性

1.0.0 以降、このプロジェクトはセマンティックバージョニングに従います。各リリースでの変更内容はCHANGELOGに記載されています。

保証対象：1.x リリースでは、以下の内容に互換性のない変更はありません。

• ツール。 save_session_checkpoint、load_session_checkpoint、list_session_checkpointsと、以下の内容が対象です。

  • 入力フィールドと必須項目
  • 出力フィールド（structuredContent）
  • 4つのアノテーションヒント

  test/contract.test.tsでは、クライアントがtools/listから受け取るこれらすべての内容を固定しています。

• チェックポイントファイル。 version: 1のJSON形式と、ファイルの保存場所（.claude-checkpoints/<session-id>.json、.prevバックアップ、従来の.claude-checkpoint）が対象です。1.x リリースでは、以前の1.xが書き込んだファイルをすべて読み取れます。

• 従来のファイル。 .claude-checkpointは、1.xを通じて読み取り可能な状態に保たれ、legacyとして一覧に表示されます。このファイルが書き込まれるのは、CHECKPOINT_SESSION_IDS=legacyを指定した場合のみです。

• 環境変数。 CLAUDE_CODE_SESSION_ID、CHECKPOINT_PROJECT_ROOT、CHECKPOINT_SESSION_IDS、SESSION_CHECKPOINT_NUDGEと、それらが受け付ける値が対象です。

• プロジェクトルートの選択方法（詳細）。

• プラグイン。 名前（session-checkpoint）、2つのフック（セッション開始時のナッジとサブエージェントの保存ガード）、および手動セットアップで登録されるdist/スクリプトのパスが対象です。

破壊的変更となるため、メジャーリリースでのみ可能です。

• ツール、入出力フィールド、または環境変数の削除や名前変更
• 入力の必須化、または受け付ける値の範囲の縮小
• 既存フィールドの意味の変更
• 以前の1.xリリースでは読み取れないチェックポイントファイルの書き込み

**マイナーリリースで許可される変更：**新しいツール、新しい任意入力、新しい出力フィールド。以前の形式のファイルも引き続き読み込める場合は、新しいチェックポイント形式のバージョンも追加できます。

保証対象外：リリースを問わず、以下は変更される場合があります。

• 再開時の概要、サーバーの指示、ツールの説明、メッセージ、警告の文言
• タイムスタンプが同じ一覧項目の順序
• src/以下のすべて。npmパッケージは実行するサーバーであり、インポートするライブラリではありません。

セキュリティとプライバシー

• ローカルのみ。 ネットワーク通信はありません。サーバーはGitのメタデータとプロジェクトのチェックポイントファイルを読み取り、現在のセッションのチェックポイントのみを書き込みます。

• シークレットのマスキング。 コマンド、メモ、概要、タスク、決定事項に含まれる以下の情報は、ディスクに書き込まれる前に«redacted»に置き換えられます。

  • *_KEY=、*_TOKEN=、*_SECRET=、*PASSWORD=の形式の代入（Header: value形式とJSON形式を含む）
  • Authorization: Bearer …ヘッダー
  • URL内の認証情報（postgres://user:pass@…）
  • --password / --token / --api-key / --secretフラグ
  • 単独で記載されたsk-…、ghp_…、github_pat_…、AKIA…、xox?-…形式のトークン

  マスキングは安全対策であり、完全な保証ではありません。ファイルをバージョン管理に含めないでください。

• 所有者のみがアクセスできる、クラッシュに強い書き込み。 ファイルはモード0600で書き込まれます。保存ごとに一時ファイルを書き込み、fsyncしてから所定の場所へリネームするため、保存中にクラッシュしても、途中まで書き込まれたチェックポイントが残ることはありません。

• 自動バックアップ。 直前の有効なチェックポイントは.claude-checkpoint.prevとして保持されます。メインファイルが破損している場合、読み込み時にバックアップが使われ、その旨が通知されます。破損したファイルが正常なバックアップを上書きすることはありません。

• サイズ上限。 各フィールドには文字数の上限があり、ファイル全体の上限は64 KBです（古いコマンドから削除されます）。そのため、チェックポイントがトークンを大量に消費するファイルになることはありません。

• シェルを使用しません。 Gitの実行には3秒のタイムアウトとGIT_OPTIONAL_LOCKS=0を指定したexecFileを使用するため、ユーザー自身のGitコマンドと競合することはありません。

• 設定には手を加えません。 チェックポイントがGitの追跡対象から除外されていない場合、保存時の応答で警告します。.gitignoreを自動編集することはありません。

• 並列ツール呼び出しにも安全です。 サーバー内でツール呼び出しを直列化するため、並行するmerge保存で更新が失われることはありません。

---

トラブルシューティング

症状	対処方法
/mcp に checkpoint が表示されない	claude mcp list を実行し、パスが絶対パスであり、dist/index.js が存在することを確認してください（npm run build）。
チェックポイントが誤ったディレクトリに書き込まれる	サーバーは作業ディレクトリにフォールバックしています。呼び出し時に projectRoot を渡すか、CHECKPOINT_PROJECT_ROOT 環境変数を設定してください。
projectRoot must be an absolute path	./app ではなく、/home/me/code/app のようなフルパスを使用してください。
ブリーフに「Saved commit … is no longer reachable」と表示される	保存後にブランチがリベースまたはリセットされました。履歴を基準に差分を計算できないため、フラグが付いたファイルは再読み込みが必要なものとして扱ってください。
警告：「not git-ignored」	.gitignore に .claude-checkpoint* を追加してください。
セッション開始時にチェックポイントについて Claude に二重に通知される	プラグインのものに加えて、独自のナッジフックも残っています。独自のフックを削除してください（セッション開始時のナッジを参照）。
セッション開始時にナッジがない	フックはプラグインにのみ含まれており、セッションの開始ディレクトリ（または CHECKPOINT_PROJECT_ROOT）にチェックポイントがある場合にのみ実行されます。SESSION_CHECKPOINT_NUDGE が off になっていないことを確認し、/hooks を実行して登録されていることを確認してください。
session: "…" names a different one	チェックポイントセレクターが session として渡されています。別のチェックポイントを読み込むには load_session_checkpoint の checkpoint を使用し、次の保存でそこから続行するには resumedFrom を使用してください。
セッション ID のないクライアントで小さなチェックポイントが多数作成される	Claude が session ID を返していないため、最初の保存ごとに新しいチェックポイントが開始されます。Claude に伝えるか、CHECKPOINT_SESSION_IDS=legacy を設定して、代わりに 1 つの .claude-checkpoint ファイルを共有してください。
サブエージェントの保存が「Subagents must not save session checkpoints」で拒否される	想定どおりの動作です。サブエージェント保存ガードが、親のチェックポイントを上書きするのを阻止しました。サブエージェントには最終回答で進捗を報告させ、メインセッションから保存してください。
「Since this checkpoint」セクションがない	プロジェクトが git リポジトリではないか、保存時点でコミットがありませんでした。

サーバーログは stderr に出力されます。Stdout は MCP プロトコル専用です。

---

開発

npm run typecheck   # strict TypeScript, src + tests
npm test            # unit tests + in-memory MCP end-to-end tests (vitest)
npm run build       # compile dist/index.js (server), dist/hook.js (nudge) and dist/guard.js (guard), and copy them to plugin/dist
npm run inspect     # open the MCP Inspector against dist/index.js

プラグインのインストールではそのまま実行するため、plugin/dist/ はコミットされています。その package.json（"type": "module"）は、バンドルを ES モジュールとして指定します。インストールされたプラグインはこのリポジトリの外に配置されるため、このファイルがないと Node はその上位にある最も近い無関係な package.json を参照します。その結果、実行のたびに警告が表示され、モジュール構文の検出に対応していない Node のバージョン（例：20.10）ではバンドルをまったく読み込めません。

src/
├── index.ts    # entry point: stdio transport, signals, stderr logging
├── hook.ts     # entry point of the plugin's SessionStart hook (dist/hook.js)
├── guard-hook.ts # entry point of the plugin's PreToolUse subagent guard (dist/guard.js)
├── guard.ts    # subagent guard: denies saves from subagents
├── hookInput.ts # reads hook input from stdin (shared by both hooks)
├── nudge.ts    # session-start nudge: finds checkpoint files without reading them
├── server.ts   # McpServer construction + server instructions
├── tools.ts    # save/load/list tool schemas and handlers
├── session.ts  # session id validation
├── listing.ts  # checkpoint listing for the "which one?" prompt
├── schema.ts   # zod schema for the checkpoint file (v1) + migrations
├── paths.ts    # project root resolution and checkpoint file names (no dependencies, shared with the hook)
├── store.ts    # checkpoint paths, atomic I/O, backup/fallback
├── git.ts      # branch/HEAD/status snapshot, blob hashing, drift detection
├── redact.ts   # secret scrubbing
└── render.ts   # checkpoint → markdown resume brief

リリース

1. プルリクエストを作成し、ブランチ上でリリースの準備をします。
   • package.json、package-lock.json、server.json（2 か所）、plugin/.claude-plugin/plugin.json、.claude-plugin/marketplace.json のバージョンを更新します。値が一致しない場合は test/metadata.test.ts が失敗します。
   • 変更内容を CHANGELOG.md の新しいバージョン見出しの下に移動します。
   • npm ci と npm run build を実行します。バージョン更新と再ビルドした plugin/dist をまとめてコミットします。
2. プルリクエストをマージします。
3. main 上のマージコミットに vX.Y.Z のタグを付けます。 新しいタグで GitHub リリースを作成する（Releases → Draft a new release を選択し、リリースノートに CHANGELOG の該当項目を使用する）か、タグをプッシュします。
4. Publish ワークフローを確認します。 新しいタグで開始され、タグが package.json と一致しない場合は公開を拒否し、session-checkpoint-mcp を npm に、server.json を MCP レジストリに io.github.daniel-munoz/claude-checkpoint-mcp として公開します。

リリースが途中で失敗した場合は、失敗したジョブを再実行しないでください。代わりに Actions → Publish → Run workflow からタグを指定してワークフローを再実行してください。すでに成功したステップはスキップされます。

公式の @modelcontextprotocol/sdk と zod を使用して構築されています。

ライセンス

MIT