本地桌面工具 · 一处搜索、整理、分析与恢复 Claude Code / Codex / CodeBuddy 的本地和 SSH 远程会话

简体中文 ｜ English

Agent-Session-Search 是一个本地桌面工具，用来搜索、整理、分析和恢复 Claude Code 与 Codex 的历史会话。

它会读取本机已有的 Claude / Codex session 文件，也可以通过 SSH 读取远程机器上的 session，建立本地搜索索引，并允许你给每个 session 添加自定义标题、标签、置顶和隐藏状态。这些额外信息都存放在独立的本地 SQLite 数据库里；索引和整理默认不会修改原始 session 文件，只有用户确认删除 session 时才会删除对应源文件。此外还接入了 CodeBuddy CLI 等，设置中可打开。

• 在一个桌面应用里统一搜索 Claude Code、Codex 和可选 CodeBuddy CLI 会话。
• 支持全文搜索：自定义标题、原始标题、首个用户问题、会话正文和项目路径。
• 支持首屏分页加载，长列表只先展示一部分 session，继续点击再加载更多。
• 支持给 session 添加自定义标题、标签、收藏、置顶、隐藏状态，也支持删除 tag 和本地 session 源文件。
• 支持按项目、环境、标签、来源、打开/关闭状态、置顶状态、隐藏状态过滤。
• 支持按最近活动、创建时间、更新时间排序。
• 支持本地环境和 SSH 远程环境；远程环境可手动刷新，也可通过远端文件监听自动同步。
• 支持从 Terminal、iTerm、Ghostty、WezTerm 或 Warp 恢复会话。
• 支持把已经打开的终端前置、复制 resume 命令，或导出 Markdown。
• 支持详情页 Markdown / code block 渲染、tool call 轨迹折叠、按 user / assistant / tool 过滤消息。
• 支持按 Today / 7D / 30D / All time 统计消息数和 token 使用量。
• 支持显示 Codex 订阅额度；Claude Code 额度可通过 statusline 快照桥接显示，设置中可隐藏。
• 支持从菜单栏或界面按钮刷新本地索引和用量统计。
• 支持 Skills 管理：查看 Codex / Claude Code 已安装的 skills、搜索、预览、按来源过滤、复制路径、打开所在目录、删除用户 skill。
• 支持 Skill 使用统计：Claude Code 通过 PostToolUse hook 记录，Codex 从本地 session 中推断读取过的 SKILL.md；统计索引写入本地 SQLite，点击刷新按钮增量更新。
• 支持 Codex / Claude Code API Provider 切换，内置 CodexZH、DeepSeek、GLM、LongCat、Kimi、MiMo 等常用预设，也支持自定义 base URL、model 和 API key。
• 支持明暗主题和中英文界面切换。
• macOS 下默认使用 Option+Space 唤起窗口，可在 Settings 里修改或关闭。

当 ~/.codex/session_index.jsonl 存在时，应用会读取 Codex 的标题元数据。没有上游标题时，会使用第一个有效用户问题作为默认标题。

SSH 远程环境不需要在远端安装 Agent-Session-Search，也不会在远端写入数据库。应用会在本机通过系统 ssh 连接远端，在远端执行一个临时 Python collector，读取远端 ~/.codex 和 ~/.claude 下的 session 摘要，再把摘要写入本机 SQLite。

远程同步方式：

• 添加或启用 SSH 环境后，会先完整同步一次最近 session 摘要。
• 如果远端有 inotifywait，会通过 SSH 长连接监听 ~/.codex/sessions、~/.codex/session_index.jsonl、~/.claude/projects、~/.claude/sessions。
• 如果没有 inotifywait 但有 fswatch，会使用 fswatch 监听 ~/.codex 和 ~/.claude。
• 如果两者都没有，会退化为每 60 秒轮询同步。
• 远程详情按需加载：列表默认只保存摘要，点开某个远程 session 时才通过 SSH 拉取对应原始文件内容。

远程机器需要：

• 能从本机通过 ssh 非交互连接。
• 安装 python3。
• 想要实时监听时安装 inotifywait 或 fswatch；没有也能使用轮询。

Agent-Session-Search 会把两类数据分开处理：

• Claude / Codex 的原始 session 文件在索引、搜索、标注时只作为只读输入；显式确认删除 session 时会删除对应源文件。
• SSH 远程 session 文件也只作为只读输入，通过 SSH 拉取摘要和按需详情。
• 自定义标题、标签、收藏、置顶、隐藏状态、搜索索引、远程环境配置、Skill 使用索引和 API Provider key 存放在 Electron userData 目录下的本地 SQLite 数据库中。
• 应用 Codex / Claude Code Provider 时，会按对应 CLI 的配置格式修改本机 ~/.codex/config.toml 或 ~/.claude/settings.json，并先写入备份。

要求 Node.js 22.13+（含 npm）。进入仓库目录后，执行下面命令即可安装依赖、构建并注册全局命令：

nvm install 22 && nvm use 22 && npm ci && npm run build && npm install -g .

如果你不用 nvm，只要本机 node --version 是 22.13 或更高版本，可以直接从 npm ci 开始执行。

装好后，在任意终端运行 agent-session-search 即可启动。应用常驻后台（菜单栏有图标），默认按 ⌥ Option + Space 唤起搜索窗口；如果和 Raycast 等工具冲突，可以在 Settings 里修改或关闭全局快捷键。

Settings 也可以通过 Cmd+, 打开；在 Appearance 里可以切换明暗主题和 English / 中文界面。

后续日常启动不需要重新执行安装命令，也不需要重新 build，直接运行：

agent-session-search

如果新终端提示 agent-session-search: command not found，通常是因为全局命令安装在 nvm 的 Node 22 目录下，但当前 shell 没有选中 Node 22。可以先运行：

nvm use 22
agent-session-search

也可以一次性设置默认 Node 版本，之后新终端就不需要手动 nvm use 22：

nvm alias default 22

确认 Node.js 22.13+ 后，在仓库目录里用 PowerShell 执行：

npm ci && npm run build && npm install -g .

装好后，在任意终端运行 agent-session-search 即可启动。应用常驻后台（任务栏/托盘有图标），默认按 Ctrl + Alt + Space 唤起搜索窗口。

更新、卸载、从源码克隆、网络镜像等详情见 Install.md。

要求：

• macOS 或 Windows
• Node.js 22.13 或更高版本
• npm

安装依赖：

npm install

运行测试：

npm test

启动开发版桌面应用：

npm run dev

构建应用：

npm run build

• README.md：中文项目说明，面向普通读者和开发者。
• docs/README.en.md：英文项目说明。
• Install.md：安装、更新、卸载说明，也包含给 Coding Agent 安全初始化项目环境的执行文档。

有任何问题，请提交issue。如果觉得我们的项目还不错，欢迎star✨。