noluyorAbi/claude-code-recap

Claude Code 内置的 `/resume` 只会列出你当前所在目录的会话。在重启、崩溃，或者在一周内穿梭于五个 repo 之后，你根本无法回答“我之前在做什么，以及我停在了哪里”。`recap` 用一个命令就能回答这个问题，并且可以在终端标签页中重新打开一整套工作环境。 ## 它的功能 `recap` 会读取 Claude Code 已经写入磁盘的会话日志，并打印出按天分组的近期会话时间线。每个会话包含：最后活动时间、绝对项目路径、简短摘要、大致轮次数、git 分支、模型、会话 ID，以及一个可以直接粘贴使用的 `cd && claude -r ` 恢复命令。 - 机器上的每个项目，而不仅仅是当前目录。 - `--pick` 可直接跳进某个会话。 - `--open` 可重新打开所有列出的会话，每个会话都在其独立的终端标签页中，并已自动恢复。 - 纯 Python 3 标准库。无依赖，无需构建。 - 默认离线且只读。唯一的网络请求途径是主动启用的 `--smart` 标志。 ## 安装 有三种可用方式，均已上线。插件市场是原生途径；`npx` 和 `curl | sh` 会将相同的 skill 安装到 `~/.claude/skills/recap`。 ### 1. 插件市场（推荐） 这个 repo 本身就是它自己的 Claude Code 市场。在任何 Claude Code 会话中只需两行命令： ``` /plugin marketplace add noluyorAbi/claude-code-recap /plugin install claude-code-recap@noluyorabi-plugins ``` 然后运行 `/reload-plugins`，并按以下方式调用： ``` /claude-code-recap:recap ``` 插件的 skill 带有命名空间前缀 `plugin-name:skill-name`，因此不会与你安装的任何其他内容发生冲突。请通过 repo (`owner/repo`) 添加市场，而不是使用指向 `marketplace.json` 的直接 URL：通过 URL 添加的市场只会下载那一个文件，并且条目的相对源 (`./`) 将无法解析。 ### 2. npx 将 skill 安装到你的 Claude Code skills 目录（`~/.claude/skills/recap` 或 `$CLAUDE_CONFIG_DIR/skills/recap`）： ``` npx claude-code-recap ``` 然后将其作为 `/recap` 调用。该包没有 postinstall 钩子；只有在你运行命令时才会执行写入操作。它会记录已写入文件的 sha256 清单，并拒绝覆盖它未安装的目录或你已编辑过的文件，除非你传递 `--force` 参数。 ``` npx claude-code-recap --force # overwrite local edits npx claude-code-recap --uninstall # remove what it installed ``` ### 3. curl 同样的安装方式，无需 Node： ``` curl -fsSL https://raw.githubusercontent.com/noluyorAbi/claude-code-recap/main/install.sh | sh ``` 与 npx 方式提供相同的保证：sha256 清单、无静默覆盖、支持 `--force` 和 `--uninstall`。 ``` curl -fsSL https://raw.githubusercontent.com/noluyorAbi/claude-code-recap/main/install.sh | sh -s -- --uninstall ``` ### 4. skills CLI 如果你使用 [`skills`](https://skills.sh) 目录 CLI，recap 会直接从该 repo 解析并安装到它管理的每个 agent 中： ``` npx skills add noluyorAbi/claude-code-recap ``` Claude Code 无需重启即可识别 `~/.claude/skills`。仅当会话启动时该目录不存在时才需要重启。 选择一种方式。同时安装 skill *和* 插件会让你同时拥有 `/recap` 和 `/claude-code-recap:recap`；它们不会冲突，但你会在 skill 列表中看到两份描述。 ## 你会看到什么 ``` ◆ recap 6 sessions · 5 projects 14d ▂▁▄▃▅▂▆█▃▅▇▄▆█ ── Today ───────────────────────────────────────────────────────────────────────────────── 1 ● 14:22 12m ago Fix the flaky auth test in the checkout flow a3f91c02 ~/repos/shop-web · ⎇ fix/flaky-auth · opus-4.8 · 46 turns cd ~/repos/shop-web && claude -r a3f91c02-7b4e-4d19-9c2a-5f83e6d1b704 2 ● 11:05 3h ago Rewrite the ingest worker to stream instead of buffer 6d20be14 ~/repos/pipeline · ⎇ main · sonnet-4.5 · 18 turns cd ~/repos/pipeline && claude -r 6d20be14-0a8f-49c7-8b31-1e4d90c7aa52 3 ● 09:41 5h ago Draft the migration plan for the billing schema c17ff5a9 ~/repos/billing-svc · ⎇ chore/migrate · opus-4.8 · 7 turns cd ~/repos/billing-svc && claude -r c17ff5a9-2e6b-4f10-9d55-b0c3e7182f44 ── Yesterday ───────────────────────────────────────────────────────────────────────────── 4 ● 22:58 1d ago Debug the flexbox overflow in the sidebar 9b3c0d67 ~/repos/shop-web · ⎇ fix/flaky-auth · sonnet-4.5 · 31 turns cd ~/repos/shop-web && claude -r 9b3c0d67-58a1-4c02-91ff-6ea27d3b8c19 5 ● 17:12 1d ago Set up the release workflow and the version check 40ea8b25 ~/.claude · opus-4.8 · 12 turns cd ~/.claude && claude -r 40ea8b25-c934-4d7e-a06b-72f1958e3dd0 ── Fri 10.07 ───────────────────────────────────────────────────────────────────────────── 6 ● 16:30 3d ago Port the CLI to the new argparse layout e58a1c93 ~/work/internal-tools/cli · ⎇ main · haiku-4.5 · 4 turns cd ~/work/internal-tools/cli && claude -r e58a1c93-6f22-4bb8-83e0-9c17d4a52b61 turns ≈ user + assistant messages · --pick jump in · --open all in tabs · --smart 1-line summaries ``` 在真实的终端中，输出是带有颜色的：按天分组的时间线（Today 为绿色，Yesterday 为琥珀色），头部有 14 天的活动迷你图，以及每个项目稳定对应的彩色圆点，因此同一个 repo 在多次运行中保持相同的颜色。当输出通过管道传输时，颜色会自动禁用，并受 `NO_COLOR` 控制。恢复命令行仅使用空格缩进，因此三击鼠标即可复制一条能直接运行的命令。 ## 参数 | 参数 | 默认值 | 功能 | |------|---------|--------------| | `--since SPEC` | 关闭 | 仅显示在时间窗口内活跃的会话：`30m`, `24h`, `7d`, `2w` | | `--project SUBSTR` | 关闭 | 仅显示绝对项目路径包含 `SUBSTR` 的会话 | | `--limit N` | `15` | 列出的最大会话数 | | `--json` | 关闭 | 机器可读的输出，包含完整的会话 ID 和恢复命令 | | `--smart` | 关闭 | 通过一次 `claude -p` 调用（联网），用真正的单句描述替换摘要 | | `--pick` | 关闭 | 交互式选择一行，然后直接 `cd` 并执行 `claude -r` 进入该会话 | | `--open` | 关闭 | 为列出的每个会话打开一个新的终端标签页并在那里恢复（macOS） | | `--claude-flags "FLAGS"` | `""` | 为每个恢复的 `claude` 提供的额外参数，按原样传递 | | `--terminal auto\|iTerm2\|Terminal` | `auto` | `--open` 驱动的应用程序；`auto` 表示如果安装了 iTerm2 则选择 iTerm2 | | `--yes`, `-y` | 关闭 | 跳过 `--open` 的确认提示；当 stdin 不是 TTY 时必需 | | `--dry-run` | 关闭 | 与 `--open` 配合：打印标签页和命令，但不执行打开操作 | | `--color` | 自动 | 即使输出通过管道传输，也强制使用 ANSI 颜色 | | `--plain` | 关闭 | 禁用所有 ANSI 颜色 | 环境变量：`CLAUDE_CONFIG_DIR` 会覆盖 `~/.claude`。支持 `NO_COLOR`、`FORCE_COLOR` 和 `CLICOLOR_FORCE`。`--open` 会读取 `CLAUDE_CODE_SESSION_ID`，因此它永远不会重新打开它当前正在运行的会话。 无需 skill 层，直接运行它： ``` python3 ~/.claude/skills/recap/recap.py --since 7d --project shop-web python3 ~/.claude/skills/recap/recap.py --json --limit 50 | jq '.[].projectPath' ``` 如果你想在 Claude Code 之外使用它，可以设置别名： ``` alias recap='python3 ~/.claude/skills/recap/recap.py' ``` ## 使用 `--open` 恢复一整套工作环境 `--open` 会获取当前列出的会话，并为每个会话打开一个新的终端标签页，同时输入恢复命令。这是在重启后回到五仓库工作环境的最快方式。 ``` # 先预览：打印 tabs，不打开任何内容 python3 ~/.claude/skills/recap/recap.py --since 24h --limit 8 --open --dry-run # 然后实际执行 python3 ~/.claude/skills/recap/recap.py --since 24h --limit 8 --open ``` 它遵循的规则： - 范围由常规过滤器决定。`--limit`、`--since` 和 `--project` 决定确切显示哪些标签页。在提交前使用 `--dry-run` 进行预览。 - `recap` 自身运行所在的会话会基于 `CLAUDE_CODE_SESSION_ID` 自动匹配并跳过。它永远不会重新打开自己。 - 项目目录不再存在的会话会被跳过并报告，绝对不会被打开。 - 如果没有 `--yes`，它会要求确认。当 stdin 不是 TTY 时（Claude Code 的 Bash 工具就是如此），除非明确传递了 `--yes` 参数，否则它拒绝打开任何东西。 - 标签页打开通过 `osascript` 驱动 iTerm2 或 Terminal，因此它仅限 macOS 使用。在其他平台上，`--open` 会退出并给出明确的消息，而 `--open --dry-run` 仍会打印命令，以便你可以将其粘贴到任何地方。 ### 关于 `--claude-flags` 的安全提示 `--claude-flags` 会原样传递给每个恢复的 `claude` 会话。这包括 `--dangerously-skip-permissions`： ``` python3 ~/.claude/skills/recap/recap.py --since 24h --limit 8 \ --open --yes --claude-flags "--chrome --dangerously-skip-permissions" ``` 请务必清楚该命令的含义。它会在 N 个不同的 repo 中启动 N 个 Claude Code 会话，每个会话都**禁用了所有权限检查**，且每个会话恢复的对话内容你可能已经不记得了。恢复的会话会携带其旧上下文，因此无论它之前正在做什么，现在都可以在不询问你的情况下继续执行。这是一个真实的爆炸半径，并且会乘以标签页的数量。 `recap` 不会阻止你。它会在打开标签页前打印一条明确的警告： ``` Opening 3 tab(s): Fix the flaky auth test in the checkout flow cd /Users/you/repos/shop-web && claude --dangerously-skip-permissions -r a3f91c02-7b4e-4d19-9c2a-5f83e6d1b704 Rewrite the ingest worker to stream instead o… cd /Users/you/repos/pipeline && claude --dangerously-skip-permissions -r 6d20be14-0a8f-49c7-8b31-1e4d90c7aa52 Draft the migration plan for the billing sche… cd /Users/you/repos/billing-svc && claude --dangerously-skip-permissions -r c17ff5a9-2e6b-4f10-9d55-b0c3e7182f44 skipped (path gone): /Users/you/repos/old-spike WARNING: --dangerously-skip-permissions disables all permission checks in every tab opened. ``` 仅在你完全控制的 repo 上使用它，并且仅在你查看了 `--dry-run` 列表之后再使用。如果你不确定某个会话之前在做什么，请去掉该标志进行恢复，让它主动询问你。 ## 工作原理 Claude Code 已经将你的会话记录到了磁盘上。`recap` 只是这些日志的读取器，仅此而已。 **数据源。** 恰好两个，都是本地文件： | 路径 | 从中读取的内容 | |------|----------------------| | `~/.claude/history.jsonl` | 快速全局索引：提示词文本、时间戳、项目路径、会话 ID | | `~/.claude/projects//.jsonl` | 对话记录，仅针对即将显示的会话进行解析：标题、git 分支、模型、轮次数、`cwd` | 遵循 `CLAUDE_CONFIG_DIR` 设置，因此支持非标准的配置目录。 **排序。** 候选记录首先按文件 mtime 排序，然后再根据文件内部真正的最后时间戳重新排序。Claude Code 在压缩和写入标题时会触及记录文件，因此仅靠 mtime 只能进行近似排序。 **摘要。** 优先顺序：Claude Code 自己的 `ai-title` 行，然后是会话的第一个真正用户提示词，最后是 `(no prompt)`。斜杠命令、系统提醒和工具结果不会被视为提示词。`--smart` 会用真正的单句摘要替换此项。 **项目路径** 始终来自日志中的 `cwd` 和 `project` 字段，绝不会从目录名称编码反向解码，因为那是有损转换。 **轮次数** 是指用户提示词加上不同的助手消息，通过消息 ID 进行分组，因此流式传输的数据块不会被计算两次。它被标记为“大致的”，因为事实确实如此。 **健壮性。** 损坏或不完整的 JSONL 行会被跳过，绝不是致命错误。`recap` 只能看到磁盘上仍然存在的会话；Claude Code 会根据自己的计划清理旧会话。 ## 隐私 此工具会读取你的对话记录，因此这里提供精确说明。 - **读取操作。** 仅读取 `$CLAUDE_CONFIG_DIR/history.jsonl` 和 `$CLAUDE_CONFIG_DIR/projects/*/*.jsonl`（默认为 `~/.claude`）。绝对不会打开你文件系统上的其他任何内容。 - **写入操作。** 无。`recap` 运行时创建、修改和删除的文件数为零。它从不触碰你的会话数据。（安装程序是例外，且它们仅写入由 sha256 清单跟踪的 `~/.claude/skills/recap`。） - **网络请求。** 默认无。默认运行是完全离线的。 - **唯一的例外是 `--smart`，** 这是可选的，默认关闭。它会通过 shell 调用一次你本地的 `claude` CLI，并且仅发送所列会话的：8 个字符的会话 ID 前缀、会话标题（前 150 个字符）以及第一个用户提示词（前 300 个字符）。不包含文件内容、不包含记录主体、不包含其他任何会话。如果你的 `PATH` 中没有 `claude` CLI，`--smart` 将被跳过并给出警告，同时使用离线摘要。 - **遥测。** 无。没有分析、没有电话-home（回传数据）、没有计数器、没有崩溃报告程序。 - **副作用。** `--open` 和 `--pick` 是仅有的会在标准输出之外执行操作的方式。`--open` 通过 `osascript` 驱动 iTerm2 或 Terminal；`--pick` 在选定的目录中 `exec`（执行） `claude -r`。两者都不会写入会话数据。 整个工具只有一个易于审计的文件：[`skills/recap/recap.py`](skills/recap/recap.py)，仅使用 Python 标准库。 ## 环境要求 - **Claude Code**，在磁盘上需有配置目录。如果 `~/.claude/projects` 不存在，`recap` 将退出并给出明确消息。 - **Python 3**，仅使用标准库。无 pip 包。CI 在 Python 3.11 环境下测试。 - **Node 18.17+**，仅在你通过 `npx` 安装时需要。运行时不需要。 - **macOS**，仅用于 `--open` 打开标签页（通过 `osascript` 驱动 iTerm2 或 Terminal）。其他所有功能，包括 `--open --dry-run`，均可在 Linux 和 Windows 上运行。 ## 卸载 ``` # npx 安装 npx claude-code-recap --uninstall # curl 安装 curl -fsSL https://raw.githubusercontent.com/noluyorAbi/claude-code-recap/main/install.sh | sh -s -- --uninstall ``` 除非你传递 `--force` 参数，否则两者都拒绝删除你自安装以来编辑过的文件。 如果你是作为插件安装的，请在 Claude Code 中使用 `/plugin` 打开插件管理器，并在那里禁用或删除 `claude-code-recap@noluyorabi-plugins`。 ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：AI辅助开发, Claude Code, SOC Prime, 会话管理, 开发工具, 自动化攻击