Session Steward

Session Steward

Session Steward 是一款面向 Codex 和 Claude Code 的本地会话管理器。它可以帮助你在各个工作区中查找旧会话或大型会话，判断哪些值得保留，并清理它能识别的相关记录。你可以通过浏览器界面或终端 CLI 使用，也可以通过 MCP 与 ChatGPT 或 Claude 配合使用。

Codex 可以删除会话，Claude Code 可以清除项目。已知要删除什么时，内置删除功能很实用。当难点在于审查这两款工具中跨工作区的多个会话时，Session Steward 就能派上用场。

• 在各个工作区中查找不活跃或大型会话。在 Codex 和 Claude Code 之间切换，然后按归档状态、名称或会话 ID 筛选。
• 先打开会话再做决定。查看近期消息、文件更改、命令和命令结果的精简时间线，以及已识别的存储占用和令牌用量。
• 先审查清理计划，再清理选定的会话。清理过程包含本地备份、事后验证，以及需要处理问题时的恢复功能。

在本地试用 Session Steward

无需全局安装，即可运行一次浏览器应用：

Session Steward 需要 Node.js 24.15 或更高版本。

npx session-steward@latest

浏览器应用仅在 127.0.0.1 上监听，不会上传会话内容。

如需持续使用，请全局安装：

npm install --global session-steward

全局安装会提供四个命令：

命令	用途
session-steward	浏览器界面
session-steward-cli	交互式终端和 JSON 输出
session-steward-mcp	MCP 会话管理
session-steward-scheduler	自动清理会话

Session Steward 支持 macOS、Linux 和 Windows。运行 session-steward 可打开浏览器界面。使用期间请保持终端打开；按 Ctrl+C 停止。

查找旧的和大型 Codex 与 Claude Code 会话

Session Steward 会读取 Codex 和 Claude Code 已在使用的本地会话文件夹。默认查找 ~/.codex 和 ~/.claude，并可让你在同一界面中切换提供方。

你可以：

• 按不活跃状态、确切工作区、活动或归档状态、名称或会话 ID 筛选；
• 按会话和工作区查看已识别的会话专属存储，并按大小排序；
• 浏览包含近期消息、文件更改、命令和命令结果的会话时间线；
• 检查新输入、缓存输入、缓存写入、输出和已记录的推理令牌；
• 将会话或工作区标记为 保留，以便手动和定时清理时跳过。

工作区的“保留”设置会涵盖该文件夹、其子目录以及此处今后创建的会话。“保留”仅影响 Session Steward 的清理操作。Codex 或 Claude Code 仍可删除各自的数据。

为什么不逐个删除会话？

如果你已经知道要删除什么，原生删除命令很有用。但它们无法满足跨工作区审查和清理的需求。

一个会话可能不只有对话记录。根据提供方和存储版本，它还可能包含历史记录或注册表条目、日志、检查点及其他关联记录。手动删除 JSONL 文件可能会遗留这些记录。

Session Steward 从会话本身着手，而不是从文件路径开始。它会查找受支持的相关记录，将它们集中显示在一份清理计划中，并保留它无法识别的存储。你可以一并审查多个候选项，而不必把每个旧会话都视为可以安全删除。

使用浏览器、CLI 或 MCP

浏览器

运行：

session-steward

选择 Codex 或 Claude Code，筛选或搜索列表，并打开不确定的会话。选择要清理的会话后，浏览器会显示受影响的记录，然后询问你是否确认。

使用 session-steward --no-open 启动，不自动打开浏览器。打开终端中显示的本地地址。

终端 CLI

启动交互式终端：

session-steward-cli

使用 Claude Code 而不是 Codex，或为其他工具返回有限的 JSON 结果：

session-steward-cli --provider claude-code
session-steward-cli --json --limit 10

使用 --inactive-days 60、--archive-status archived 或 --workspace /path/to/project 等选项进行筛选。使用 --events 查看时间线，使用 --tokens 查看令牌用量，使用 --sort size 将最大的会话排在最前面。运行 session-steward-cli --help 查看所有选项。

将 MCP 与 ChatGPT、Codex 或 Claude Code 搭配使用

连接一次本地 MCP 服务：

codex mcp add session-steward -- session-steward-mcp

或将其连接到 Claude Code：

claude mcp add --scope user session-steward -- session-steward-mcp

注册表安装程序可以通过 npx session-steward@latest mcp 启动同一服务，无需全局安装。

然后，你可以让客户端查找不活跃的会话、比较 Codex 与 Claude Code 已识别的会话存储、检查会话、保留工作区、清理指定会话、恢复备份，或管理清理计划。

Session Steward 会将清理、恢复和计划管理标记为具有破坏性的 MCP 操作，以便客户端应用其配置的审批策略。

关闭客户端后，自动清理仍会在后台继续运行。通过 MCP 或浏览器创建和管理计划。卸载 Session Steward 前，请停止调度器：

session-steward-scheduler --stop

对于其他 MCP 客户端，请将名为 session-steward 的本地 stdio 服务配置为使用命令 session-steward-mcp。

MCP 进程会使用 Session Steward 保存的提供方文件夹；如果没有保存的文件夹，则使用默认文件夹。其服务命令可以通过 --codex-home 或 --claude-home 设置启动文件夹，而其 manage_settings 工具可以更改保存的文件夹。一次性的浏览器或 CLI 覆盖设置不会延续到后续的 MCP 进程。

MCP 服务在本地运行，但会话详情可能包含消息、命令、文件名和工作区路径。你的 MCP 客户端可能会将这些信息发送给其 AI 提供商。

先查看将要删除的内容

手动清理时：

1. 选择会话。
2. 关闭任何可能仍处于活动状态的已选会话。
3. 查看 Session Steward 生成的清理计划。
4. 确认计划。
5. Session Steward 会创建本地恢复备份。
6. 它只会移除已审核计划中受支持的记录。
7. 它会检查这些记录是否已删除。

每个界面在更改数据前都会重新验证已选会话。如果 Session Steward 能检测到某个已选会话处于活动状态，预检或清理就会停止。无法检测时，它会提醒你确认已选会话均已关闭。

标准清理和彻底清理

标准清理会删除所选会话所属的受支持对话记录、历史记录、注册表项、日志和关联文件。这是常规选项。

彻底清理还会删除其他已识别的会话专属数据。对于 Codex，这可能包括受支持的 Desktop 引用、记忆输出和目标记录。对于 Claude Code，则包括已识别的文件检查点。

当检测到的存储布局不受支持时，无法使用彻底清理。标准清理仍可删除 Session Steward 能够安全识别的记录。

备份和恢复行为

恢复备份存储在活动提供方文件夹下的 session-steward-backups/ 中。

如果通过浏览器或交互式终端执行清理时需要处理问题，备份会保留，直到你决定是否恢复。浏览器会提供 恢复 选项，终端会显示备份位置，供 restore 命令使用。MCP 和计划清理会尝试自动恢复。

清理成功后，Session Steward 会在条件允许时删除恢复备份。恢复操作会先为当前文件创建临时安全备份，随后在恢复成功后尝试删除两个备份。如果无法完成恢复或删除备份，恢复数据会保留下来，Session Steward 也会告知你。

清理不会触及的内容

• 登录数据和已保存的 API 凭据
• 配置、插件、缓存和自定义提示词文件
• 项目文件、Git 仓库和工作树
• 不在审核后清理计划中的会话
• 存储在你的 ChatGPT 或 Claude 账户中的对话
• Claude Code 工作树、分支、仓库、远程会话、SSH 会话和 Cowork 数据

提供方文件夹和平台支持

浏览器会显示当前活动的提供方文件夹。选择 更改，即可选择另一个现有文件夹，并将其保存供之后的浏览器、终端和 MCP 会话使用。

如需在浏览器中临时覆盖：

session-steward --codex-home /path/to/.codex
session-steward --claude-home /path/to/.claude

CLI 和 MCP 命令接受相同的标志。覆盖设置仅对当前进程生效，不会替换已保存的文件夹。

Codex 和 Claude Code CLI 会话支持 macOS、Linux 和 Windows。Claude Desktop 本地会话也支持 macOS 和 Windows。在 Windows 上，默认提供方文件夹为 %USERPROFILE%\.codex 和 %USERPROFILE%\.claude；系统会检测独立版和 Microsoft Store 版 Claude Desktop 的数据位置。

在 WSL 中，Session Steward 使用 Linux 主文件夹。从 Windows 运行它，即可管理 Windows 配置文件中的会话。

归档 Claude Desktop 会话不会将其删除。在明确将其纳入清理之前，该会话仍可使用。Session Steward 不会删除 Claude 工作树。

更新或卸载

session-steward update
npm uninstall --global session-steward

如果 npm 需要 root 权限，更新命令会在使用 sudo 重试前征求你的同意。

卸载不会删除提供方会话、恢复备份或已保存的文件夹偏好设置。

故障排除

• 浏览器未打开： 运行 session-steward --no-open，然后打开终端中显示的本地地址。
• 未找到会话： 检查所选提供方和显示的主文件夹。使用 更改，或传入一次性主文件夹覆盖设置。
• 无法使用彻底清理： 未识别的存储会保持不变，但仍可能可以使用标准清理。
• Node.js 版本过旧： 安装 Node.js 24.15 或更高版本，然后再次运行 Session Steward。

基准测试

在配备 Node.js 24.15.0 的 arm64 Mac 上进行的当前基准测试：

场景	规模	耗时	测得的内存增长
分页会话列表	50,003 个会话	26 ms	0.16 MB 堆内存
会话大小索引	20,003 个会话	冷启动 85 ms，热启动 9.7 ms	RSS 峰值 30 MB
仅通过转录内容发现	5,003 个会话	662 ms	4.02 MB 堆内存

使用以下命令运行规模基准测试：

npm run benchmark:scale
npm run benchmark:overview
npm run benchmark:size
npm run benchmark:discovery
npm run benchmark:transcripts

测试结果会因硬件、磁盘速度和会话布局而异。测试和基准测试使用临时合成数据，不会读取或修改本地会话。

支持

通过 GitHub Issues 报告错误、申请支持新的提供方，或分享 Session Steward 无法识别的存储格式。查看更新日志了解版本发布历史。

Session Steward 是一个独立项目，与 OpenAI 或 Anthropic 无关，也未获得其认可。

许可证

MIT