session-recap

session-recap

English | 中文

记住每次 AI 编码会话的目的。

_{适用于任意长度、来自任意 Agent 的会话，通过 MCP、本地查看器或插件记录意图 · 关键决策 · 变更内容 · 未完事项 · 恢复工作的起点}

     

---

项目不断发展，每个项目中的会话数量也随之增加，而且常常涉及多个 Agent。几周之后，会话记录可能已长达 100 MB，而你早已不记得自己为何开始、做了哪些决定，以及哪些工作只完成了一半。

session-recap 会读取会话的完整记录，并生成简短、结构化的回顾。你可以通过任意 MCP 客户端（Codex、Cursor、Zed、Cline、Gemini CLI、OpenCode、Claude Code……）、用于查看所有 Agent 会话的本地查看器、命令行，或适用于 Claude Code、dsh 和 Codex 的原生插件来使用它。

部分	回答的问题
意图	我最终想要实现什么？
关键想法与决策	我们做了什么选择？为什么？否决了哪些备选方案？
变更内容	文件、功能、文档、提交、PR
未完事项	哪些工作尚未完成、尚未验证，或仍有疑问？
恢复工作的起点	今天最合理的下一步是什么？

每份回顾还包含一张地图：展示工作经历的各个阶段（并标出方向转变），一直细化到“你现在在这里”；列出关键决策以及被否决的方案；并汇总已交付、未完成和已放弃的事项。回顾会使用你最常用的语言撰写。

快速开始

npm install -g session-recap
session-recap mcp-config            # prints the MCP entry for your client
session-recap serve                 # opens the local viewer

然后，在你的 Agent 中输入：“总结一下本次会话”、“我在这个项目中的上一次会话是关于什么的？”、“总结一下这个会话”。

无需 API 密钥。 通过 MCP，你正在与之对话的 Agent 会使用自己的模型撰写摘要；session-recap 只会读取并精简对话记录。也可以为 session-recap 配置自己的模型（供命令行和查看器的 撰写摘要 按钮使用）。

也可以无需安装直接运行：npx session-recap …。session-recap 没有依赖项，也不会运行安装脚本。开发版本：npm install -g github:BruceXcluding/session-recap --allow-git=all（npm 12 不加此标志时会阻止从 GitHub 安装）。

要求： Node.js 20+、python3（macOS 自带）以及用于 dsh 会话的 zstd 命令或 Python 3.14+。

使用方式

	适用场景	使用方法
MCP 服务	任何 MCP 客户端	session-recap mcp-config <client>，见下文
本地查看器	浏览每个 Agent 的会话、摘要和地图	session-recap serve
Claude Code 插件	在聊天旁显示摘要 / 地图面板	/plugin install session-recap --marketplace BruceXcluding/session-recap
dsh 插件	在 dsh 中使用 /recap 和 session_recap 工具	packages/dsh
Codex 插件	为 Codex 打包的 MCP 服务	plugins/codex
命令行	脚本、快速查看、其他格式	session-recap、session-recap list

MCP 服务

session-recap mcp-config <client> 会打印适用于 claude、codex、cursor、gemini（以及 Qwen Code）、opencode、zed、vscode 或 cline 的配置项，其中包含绝对路径，以便从程序坞启动的 IDE 能找到它。例如：

session-recap mcp-config codex >> ~/.codex/config.toml
claude mcp add --scope user session-recap -- session-recap mcp

工具：

工具	功能
list_sessions	列出所有 Agent 的会话，可按标题词语、项目文件夹或 Agent 筛选
recap_session	获取当前会话（或指定会话）的摘要：如果会话未更改，则返回已保存的摘要；否则，如果配置了 session-recap 的模型，则由该模型撰写摘要；若未配置，则返回精简后的无敏感信息对话记录，以及供调用方 Agent 撰写摘要的说明
save_recap	保存 Agent 撰写的摘要以供复用，并在下次根据新增内容更新

recap_session 还接受 format 参数，可使用 standup、handoff 或 pr 格式代替摘要。

本地查看器

运行 session-recap serve 会打开 http://127.0.0.1:4711，其中包含按项目文件夹分类、按时间分组并可按 Agent 筛选的所有 Agent 会话；每个会话的摘要和地图；以及在配置了模型时显示的 撰写摘要 和 更新摘要。它会读取 Claude Code 插件、命令行和 MCP 客户端撰写的摘要。它仅在本地回环地址上响应，并只响应它打开的浏览器标签页。

Claude Code 插件

/session-recap 会总结你当前所在的会话；/session-recap browse 会列出项目和会话；/session-recap <name> 会按名称打开项目或会话。面板会显示摘要和地图，使用会话自己的模型（或在 模型 下选择的模型），并优先显示你的 Claude Code 会话，只需轻点一下即可切换到 所有 Agent。

命令行

命令	功能
session-recap [words]	总结标题中包含指定词语的会话；不提供词语时，总结此文件夹中最新的会话
session-recap list [words]	列出会话（调用方 Agent 的会话；使用 --all 列出所有 Agent 的会话）
session-recap --format standup	改为生成站会记录（也可用 handoff、pr）
session-recap --dry-run	显示将要发送的内容大小，以及移除的敏感信息数量，不调用模型
session-recap models	列出你的服务提供商提供的模型
session-recap config set model <id>	保存设置（partModel、api、baseUrl；通过标准输入使用 config set apiKey - 设置密钥）

命令行使用的模型：SESSION_RECAP_API（anthropic 或 openai）、SESSION_RECAP_BASE_URL、SESSION_RECAP_API_KEY、SESSION_RECAP_MODEL，或 ANTHROPIC_*、DEEPSEEK_API_KEY、OPENAI_API_KEY。

支持的 Agent

Agent	读取会话的位置
Claude Code	~/.claude/projects/
Codex	~/.codex/sessions/、archived_sessions/（不包含审查线程）
dsh (deepseek-harness)	~/.dsh/sessions/（zstd；不包含子 Agent 会话）
OpenCode	~/.local/share/opencode/opencode.db

想添加其他 Agent？添加 Agent 只需实现一个读取器并添加一个测试，也可以提出请求。

隐私

• 本地运行。 会话在你的机器上读取。文本只会在生成回顾所需的模型调用中离开本机：调用你的 Agent（MCP、插件）所用的模型，或你配置的模型（CLI、查看器）。不收集遥测数据。
• 先移除秘密信息。 在任何文本发送给模型之前，密钥、令牌、私钥、URL 中的凭据以及 PASSWORD=… 这类赋值都会替换为 [REDACTED:<kind>]。--dry-run 会显示替换数量。此功能基于模式匹配，因此无法识别所有格式：请参阅 SECURITY.md。
• 发送的内容是精简后的对话记录：你的提示词、每轮的最终回复、提交和 PR，以及编辑过的文件。不包含工具输出和中间回复。

令牌用量

列出会话时不会调用模型。对于一个实际的 179 MB Claude Code 会话（220 条提示词），首次生成回顾会发送约 195k 个字符（约 96k 个令牌）；会话继续后，更新只会读取新提示词。较长的会话会分成若干部分进行精简，每部分不超过 75k 个字符，并缓存各部分的笔记；也可以使用更便宜的模型来精简这些部分（partModel）。

工作原理

saved sessions (Claude Code · Codex · dsh · OpenCode)
        │
hooks/digest.py      one reader per agent → turns (prompt, actions, final reply, edits) → secrets removed
        │
core/recap.mjs       parts → notes (parallel, cached) → one call writes the recap and its map, or updates it
        │
MCP server · viewer · CLI · Claude Code pane · dsh tool and /recap      (one cache: ~/.cache/session-recap)

输出采用版本控制：请参阅 docs/data-format.md 和 schema/recap-v1.schema.json，以构建自己的查看器或导出工具。

贡献

欢迎贡献 Agent、回顾格式、翻译和查看器。请从 CONTRIBUTING.md 开始；添加 Agent 和添加格式（在 core/formats.mjs 中添加一个条目）是最容易上手的贡献。

许可证

MIT