claude-checkpoint-mcp

claude-checkpoint-mcp

在本地保存 Claude Code 会话状态，这样即使发生崩溃、执行 /clear 或达到上下文上限，也不必让 Claude 从头重建上下文。

claude-checkpoint-mcp 是一个本地的 Model Context Protocol 服务，提供两个工具：

• save_session_checkpoint 将会话的工作状态写入项目中的一个小型 JSON 文件。
• load_session_checkpoint 将该文件转换为精简的恢复摘要。

它完全在你的机器上运行，不会向任何地方发送数据。

---

目录

• 原因：别再为相同的上下文重复付费
• 工作原理
• 安装
• 配置
  • Claude Code
  • Claude Desktop
  • 其他 MCP 客户端
• 用法
• 工具参考与示例
• .claude-checkpoint 文件
• 安全与隐私
• 故障排除
• 开发

---

原因：别再为相同的上下文重复付费

一次较长的 Claude Code 会话会积累大量上下文：

• 你要完成什么；
• 哪些方案已经失败；
• 哪些文件很重要；
• 哪项测试仍未通过。

以下情况都可能在任务进行期间清除这些内容：

• 终端崩溃、SSH 断开或笔记本电脑休眠；
• 上下文窗口用尽；
• 执行 /clear 以开启一个新的窗口。

下一次会话会从空白状态开始。为了回到之前的进度，Claude 必须重建这些上下文：

• 重新读取文件，弄清楚哪些内容被改动以及原因。每次读取文件都会消耗输入令牌。
• 重新执行探索：grep、git diff、ls、运行测试，全都只是为了重新发现当前状态。
• 重新解释。 你要再次输入目标、约束和走不通的方案，或者 Claude 得自己费力重新发现那些失败的尝试。

每次这样的交互都会再次发送不断增长的对话作为输入，因此成本会不断累积。

claude-checkpoint-mcp 用一次简短、结构化的读取，取代上述重建过程：

	不使用检查点	使用 load_session_checkpoint
恢复目标与约束	你重新输入，或由 Claude 推断	摘要中的一个部分
确认已完成和待处理的事项	重新从代码和 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 会收到指示，在会话开始时加载，并在完成里程碑后、执行高风险操作前以及对话变长时保存。无需每次都提示它。

---

安装

要求：Node.js 20+ 和 git。git 是可选的，但没有它就无法检测偏移。

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

服务入口现在位于 dist/index.js。

---

配置

Claude Code

作为插件（最简单）。 此仓库也是 Claude Code 插件市场。无需克隆或构建任何内容：

claude plugin marketplace add tenlean/claude-checkpoint-mcp
claude plugin install claude-checkpoint-mcp@tenlean

重启 Claude Code，然后 /mcp 应显示 plugin:claude-checkpoint-mcp:claude-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"]
    }
  }
}

无论采用哪种方式，都要将 checkpoint 文件添加到项目的 .gitignore 或全局 gitignore 中：

.claude-checkpoint*

Claude Desktop（claude_desktop_config.json）

打开配置文件：

操作系统	路径
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 保存一个 checkpoint"）。参见项目根目录的确定方式。

其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以运行此服务：

node /absolute/path/to/claude-checkpoint-mcp/dist/index.js

---

用法

服务内置的说明会自动覆盖常见情况。你也可以直接向 Claude 提出请求。

保存：

• "记录我们的进度。"
• "运行迁移前保存一个 checkpoint。"
• "更新 checkpoint，把我们刚才完成的工作合并进去。"

恢复（在新会话中）：

• "从上次停下的地方继续。"
• "加载 checkpoint 并继续。"

恢复摘要示例

这是 load_session_checkpoint 的实际输出。在此情景中，保存后有一个文件未经更改便提交了，随后一位队友编辑了 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-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。详见下文。
projectRoot	string（绝对路径）		覆盖根目录解析方式

完整保存：

{
  "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)."]
}

load_session_checkpoint

只读。读取检查点、检查是否存在偏移，并返回摘要。

参数	类型	必填	描述
format	"brief" | "full"		默认值为 brief（Markdown 格式，如上文所示）。full 返回完整的检查点 JSON 以及偏移信息。
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，并附上“没有可继续的内容”消息。这不会被视为错误。

如何选择项目根目录

1. projectRoot 参数
2. CHECKPOINT_PROJECT_ROOT 环境变量
3. 客户端支持 MCP roots 时，使用客户端的第一个 file:// 根目录
4. 服务进程的工作目录

路径必须是绝对路径，并且必须是现有目录。符号链接会被解析。文件始终写入 <root>/.claude-checkpoint。

---

.claude-checkpoint 文件

这是纯文本、带版本号的 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": "claude-checkpoint-mcp", "version": "0.1.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 中重新生成
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

路径始终相对于项目根目录。文件不会存储绝对路径。

---

安全与隐私

• 仅限本地。 不会发起任何网络请求。服务会读取 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（最早的命令会优先删除），因此检查点不会膨胀成令牌的收集池。

• 不使用 Shell。 Git 通过带有 3 秒超时的 execFile 运行，并设置 GIT_OPTIONAL_LOCKS=0，因此绝不会与您自己的 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	请使用完整路径，例如 /home/me/code/app，而非 ./app。
摘要提示“Saved commit … is no longer reachable”	保存后分支经过了变基或重置。无法依据历史记录计算偏移，因此请将标记的文件视为需要重新读取。
警告：“not git-ignored”	将 .claude-checkpoint* 添加到 .gitignore。
没有“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 to dist/
npm run inspect     # open the MCP Inspector against dist/index.js

src/
├── index.ts    # entry point: stdio transport, signals, stderr logging
├── server.ts   # McpServer construction + server instructions
├── tools.ts    # save/load tool schemas and handlers
├── schema.ts   # zod schema for the checkpoint file (v1) + migrations
├── store.ts    # project root resolution, 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

使用官方 @modelcontextprotocol/sdk 和 zod 构建。

许可证

MIT