CC Sessions 用来管理 Codex、Claude Code、OpenCode 和 Cursor 保存在本机的会话。你可以在一个界面里查找对话、预览内容、备份恢复、移动会话目录,也可以修复部分索引和可见性问题。
下载最新版 · 查看功能 · 进阶功能 · 常见问题 · 开发与打包
| 你属于哪类用户 | 推荐方式 | 从哪里开始 |
|---|---|---|
| 在电脑上使用 Codex、Claude Code、OpenCode 或 Cursor | 桌面版 | 安装 |
| 在 WSL、服务器或 SSH 环境中管理会话 | cc-sessions 命令行或自带网页界面 |
命令行与 WSL |
| 想修改源码或自行构建安装包 | 从源码运行 | 开发与打包 |
会话读取、搜索、编辑和备份都在本机完成。应用检查更新时会访问 GitHub Releases。
| 模块 | 可以做什么 | Codex | Claude Code | OpenCode | Cursor |
|---|---|---|---|---|---|
| 会话浏览 | 按标题、首条消息、目录或 ID 查找会话 | 支持 | 支持 | 支持 | 支持 |
| 会话整理 | 重命名、删除、按项目分组,并复制继续对话的命令 | 支持 | 支持 | 支持 | 支持 |
| 正文搜索与预览 | 搜索完整对话,按时间线查看消息和工具过程 | 支持 | 支持 | 支持 | 支持 |
| 编辑与撤销 | 修改文本、删除上下文事件、撤销编辑或恢复原始快照 | 支持 | 支持 | 支持 | 不支持 |
| 备份与恢复 | 为选中的会话创建备份,并在需要时恢复 | 支持 | 支持 | 支持 | 支持 |
| 导入与导出 | 生成可迁移的会话包,或导出为 Markdown | 支持 | 支持 | 支持 | 支持 |
| 移动会话目录 | 把会话关联到新的项目目录,并更新相关记录 | 支持 | 支持 | 支持 | 不支持 |
| 归档 | 隐藏暂时不用的会话,之后可以取消归档 | 支持 | 不支持 | 支持 | 支持 |
| 会话转换 | 创建新的可续聊会话 | 支持 | 支持 | 不支持 | 只能转出 |
| Memory 管理 | 新建、浏览、编辑、重命名和删除项目 Memory 文件 | 不接管 | 支持 | 不支持 | 不支持 |
| 子代理会话 | 单独筛选由子代理产生的会话 | 支持 | 支持 | 支持 | 随主会话管理 |
| 会话复制与分支 | 复制完整会话,或从指定消息位置创建副本;Codex 另支持模型服务分支 | 支持 | 支持会话复制 | 支持会话复制 | 不支持 |
| 使用统计 | 查看会话趋势、项目、模型和活跃时间 | 支持 | 支持 | 支持 | 支持 |
| 修复工具 | 修复部分索引、项目配置和列表可见性问题 | 支持 | 部分支持 | 不支持 | 清理数据库残留 |
会话转换会创建新的目标会话,不修改来源文件。编辑、导入、移动、恢复和删除会写入本地数据。桌面版会在高风险操作前显示确认信息,CLI 交互菜单会要求输入 yes。
Cursor 的会话存在一个共享数据库里,改动方式和其他三个工具不同,使用前请看 Cursor 会话。
前往 Releases,按系统和使用方式选择文件。下表中的 <版本号> 对应 Release 显示的版本数字,例如 0.5.3。
| 系统与用途 | 推荐下载 | 说明 |
|---|---|---|
| Windows 常规安装 | CC.Sessions_<版本号>_x64-setup.exe |
推荐大多数 Windows 用户使用 |
| Windows MSI 安装 | CC.Sessions_<版本号>_x64_en-US.msi |
适合需要 MSI 的安装环境 |
| Windows 便携版 | cc-session-manager-portable-v<版本号>-windows.exe |
下载后直接运行,不创建卸载项 |
| Windows 便携压缩包 | cc-session-manager-portable-v<版本号>-windows.zip |
解压后运行,应用更新会替换该目录中的程序 |
| macOS Apple Silicon | CC.Sessions_<版本号>_aarch64.dmg |
适用于 M 系列芯片 |
| macOS Intel | CC.Sessions_<版本号>_x64.dmg |
适用于 Intel Mac |
| macOS 解压版 | CC.Sessions_aarch64.app.tar.gz 或 CC.Sessions_x64.app.tar.gz |
根据芯片选择,普通用户优先下载 DMG |
| Debian / Ubuntu | CC.Sessions_<版本号>_amd64.deb |
使用系统软件包安装 |
| Fedora / RHEL | CC.Sessions-<版本号>-1.x86_64.rpm |
使用系统软件包安装 |
| 其他 Linux 桌面 | CC.Sessions_<版本号>_amd64.AppImage |
赋予执行权限后运行 |
命令行版本使用单独的 ZIP 包:
| 系统 | 推荐下载 |
|---|---|
| Windows | cc-sessions-cli-v<版本号>-windows.zip |
| macOS Apple Silicon | cc-sessions-cli-v<版本号>-macos-arm64.zip |
| macOS Intel | cc-sessions-cli-v<版本号>-macos-intel.zip |
| Linux | cc-sessions-cli-v<版本号>-linux.zip |
Release 最下方的 Source code (zip) 和 Source code (tar.gz) 是 GitHub 自动生成的源码压缩包,不是桌面版安装包。
第一次打开后,到设置页确认 Codex、Claude Code、OpenCode 和 Cursor 的数据路径。应用会尝试使用默认位置,没有安装的工具可以留空。
- 在顶部选择要管理的工具。
- 先打开会话列表,确认标题、项目和消息预览正常。
- 需要修改、迁移或删除会话时,先创建备份。
- 导入到另一台电脑时,在导入页面检查项目路径映射。
所有桌面版都可以检查 GitHub Release。Windows 安装版和便携版还可以校验下载文件并自动安装,便携版会替换当前解压目录中的程序文件。macOS、Linux 和命令行自带的网页界面会提供下载入口,不会自动替换当前程序。
桌面版的「设置 → 版本更新」支持两项可选网络设置,可单独使用或同时使用:
- 更新代理地址:用于检查版本和下载更新包。支持 HTTP、HTTPS、SOCKS5 和 SOCKS5H,例如
http://127.0.0.1:7890或socks5h://127.0.0.1:1080,端口需与本地代理软件一致。留空沿用默认网络。 - 下载加速地址:默认填入
https://ghproxy.net/,可自行修改,清空后直接从 GitHub 下载。填写支持拼接 GitHub 完整下载链接的服务前缀,默认下载链接形如https://ghproxy.net/https://github.com/ccpopy/cc-sessions/releases/download/...。只影响 Windows 应用内更新包下载;版本信息和校验值仍从 GitHub 获取。
检查和下载会使用当前填写的值,点击「保存设置」后供下次使用。更新包仍须通过大小与 SHA-256 校验。网页界面及外部打开的下载页面使用浏览器的网络和代理设置。
- 浏览、搜索和预览不会修改会话。
- CC Sessions 不要求账号,也不会把会话上传到第三方服务。手动更新或打开项目、发布页面时会联网;更新请求可按设置经过代理或下载加速服务。
- 编辑前会保存快照,可以逐步撤销,也可以恢复到编辑前状态。
- 移动目录会检查目标冲突和写入结果。失败时会尝试恢复原状态。
- OpenCode 和 Cursor 的会话包只包含所选会话的数据,不包含账号信息、登录凭据或本机分享密钥。Cursor 的
state.vscdb里混有凭据和全部工作区状态,因此备份和会话包都只取该会话自己的记录,不会整库复制。 - 修改 Cursor 会话前需要完全退出 Cursor。它会在内存里缓存会话状态,运行期间改数据库很可能被它按旧状态覆盖回去,因此应用检测到 Cursor 在运行时会直接拒绝写入。
- 跨机器导入时,桌面版和自带网页界面可以把原项目路径映射到新电脑的目录。
- 覆盖导入和覆盖恢复不会自动再创建一份备份。重要会话仍建议保留独立备份,尤其是在移动目录、覆盖恢复或批量删除前。
普通预览只显示用户消息和每轮最终答复,避免把运行过程、工具调用和内部上下文混在正文里。需要排查问题时,可以切换到全部事件,查看完整时间线。
用户和助手的普通文本可以修改或删除。Codex 的加密推理和 Claude Code 的签名思考不能改写,只能整段删除。删除工具事件时,应用会同时处理能够确定属于同一次调用的相关记录。
Codex、OpenCode 和 Cursor 支持归档,Claude Code 暂不支持。归档不会删除会话,普通列表会隐藏归档记录,切换到归档视图后可以取消归档。
Codex 归档视图会按归档来源分组显示:我的归档(手动归档,以及没有来源标识的归档)、切换模型服务时自动归档的同步分支、备份恢复或会话包导入产生的迁移记录;可以用顶部筛选条只看某一类。导出页会保留归档记录供手动选择,并显示“已归档”徽标。Codex 使用本地归档目录保存会话文件,OpenCode 使用自身的原生归档状态。
备份用于在本机恢复误操作,会话包用于迁移到另一台电脑,Markdown 用于阅读、分享或交给其他 AI 作为上下文。Markdown 不能导回原工具成为可续聊会话。
跨机器导入时,桌面版和自带网页界面可以重新指定项目路径。直接使用命令行导入会沿用会话包中的原路径,目录结构不同的电脑更适合使用带界面的导入页面。
主会话和子代理会话可以分开查看。列表、搜索、项目分组和大小排序都支持子代理筛选,但子代理会话不参与 Codex 与 Claude Code 的格式转换。
Cursor 是例外:它的子会话只跟着主会话管理,列表里不单独出现,删除主会话时会连同它的子会话一起删掉。这样可以避免删掉子会话后,主会话留下指向已消失会话的引用。
Codex 用户还可以处理切换模型服务配置后留下的旧会话,或从较早的稳定对话位置创建新分支。创建回溯分支时,应用会保留来源会话,并把原来的当前分支归档。
在会话卡片上点击「复制会话」可创建完整副本;打开预览后,点击消息上的「复制到此处」可复制从开头到该消息的记录,包含所选消息。副本标题添加 (fork),保存在同一项目下,可从副本卡片复制继续对话的命令。原会话保留,副本不继承文件撤销历史或子代理状态。
实现依据为 Anthropic Agent SDK 的离线 fork_session。
会话卡片上的「复制会话」会复制全部消息;预览中的「复制到此处」会按消息顺序复制到所选内容所属的整条消息,包含这条消息的全部文字、思考、工具和其他内容块。副本保存在同一项目下,标题添加 (fork #1),再次复制副本会递增编号。可从副本卡片复制 opencode --session <新会话 ID> 命令继续对话。
原会话保留,副本不继承待办、分享、撤销、归档或子会话状态。当前支持 opencode.db 的 message / part 格式;使用新版 session_message 格式的会话会明确报错,不会生成不完整的副本。
实现依据为 OpenCode 1.18.30 的官方 fork 和 SQLite 写入规则,已使用官方程序对照验证。
简洁模式是默认选项,只保留用户消息和稳定的最终答复,适合继续对话。原生模式会尝试保留工具调用、图片和过程消息,适合需要完整上下文的场景,但兼容性不如简洁模式稳定。
Codex 与 Claude Code 之间可以互相转换。Cursor 只能转出,可以转成 Claude Code 或 Codex 会话继续聊,但不能把别的工具的会话转进 Cursor——Cursor 的编辑器内会话没有命令行入口,转进去也没法打开。
转换始终创建新会话,不会修改来源文件。OpenCode 暂不参与格式转换。
Cursor 的会话不是一个会话一个文件,而是全部存在 state.vscdb 这一个数据库里,所以有几点和其他工具不同。
改动前要先退出 Cursor。 归档、重命名、删除、清理和压缩都会先检查 Cursor 是否在运行,在运行就直接拒绝。
子会话跟着主会话走。 详见子代理与 Codex 分支。
删除会真正清干净。 Cursor 自己删会话时,检查点、代码差异、文件快照等数据会留在库里不再回收。CC Sessions 删除时会把这些一并带走。
数据库可能比你以为的大得多。 长期使用后,库里会积压大量已删会话的残留。修复页的“Cursor 数据库残留”可以先诊断再清理:
| 类别 | 是什么 | 会不会丢对话 |
|---|---|---|
| 空会话 | 只有会话头、一条消息都没有 | 不会 |
| 孤儿记录 | 会话头已经不在,检查点和气泡还留着 | 不会 |
| 无引用的内容块 | 没有任何会话引用得到的文件快照和代理消息 | 不会 |
| 无主子会话 | 父会话已经不在,界面上再也访问不到 | 会 |
| 项目目录已不存在 | 会话有完整对话,只是当初的项目目录被删或改名 | 会 |
前三类默认勾选,后两类需要自己确认。清理只把数据库内的页面标成空闲,文件不会立刻变小,要点“压缩数据库”才会把磁盘还回去。几 GB 的库压缩需要几分钟。
判断“无引用的内容块”要做一次全库可达性扫描,大库上诊断需要一些时间。判定规则取的是宽松口径,宁可多留也不会误删;扫描中只要有一处读不出来,这一类就整体跳过,不影响其他类别的清理。
统计页汇总本机的 Codex、Claude Code、OpenCode 和 Cursor 数据,可以查看会话数量、活跃趋势、常用项目、模型分布和活跃时段。没有安装或没有配置的数据源会按零会话处理,不影响其他工具。
修复前可以打开“仅预览”,先查看将要发生的变化。
| 工具 | 适用情况 | 会不会改正文 |
|---|---|---|
| 修复会话列表索引 | Codex 会话文件存在,但列表中找不到 | 不会 |
| 重建会话数据库记录 | Codex 列表缺少标题、目录或时间信息 | 不会 |
| 清理无效记录 | 列表指向的会话文件已经不存在 | 不会删除仍存在的会话文件 |
| 清理分支残留 | Codex 分支状态冲突,或当前分支记录丢失 | 不会改写会话正文 |
| 克隆到当前模型服务 | Codex 切换模型服务配置后,旧会话无法直接使用 | 创建副本,不改来源 |
| 补全归档来源标记 | 旧版归档会话缺少来源记录,自动识别切换模型服务产生的克隆分支和回溯分支 | 只写 CC Sessions 自己的来源记录,不改会话文件 |
| Claude 列表可见性修复 | Claude Code 能续聊,但会话列表不显示标题 | 会在文件末尾补充标题记录 |
| Cursor 数据库残留 | Cursor 数据库越用越大,里面积压了已删会话的数据 | 只删已经没有会话的记录 |
| 压缩 Cursor 数据库 | 清理之后磁盘占用没有回落 | 不会改会话数据 |
命令行版适合 WSL、服务器、SSH 和没有桌面环境的机器。请从 Release 下载安装部分列出的对应系统 CLI 压缩包。
Windows PowerShell:
.\cc-sessions.exemacOS 或 Linux:
chmod +x cc-sessions
./cc-sessions把程序加入 PATH 后,可以直接使用 cc-sessions。不带子命令时会进入交互菜单。菜单支持翻页、多选、预览、搜索、备份、导入导出、移动目录和修复诊断。
菜单中使用 n 和 p 翻页,b 返回上一层,m 返回主菜单,0 退出。输入 s 可以多选当前页会话,u 取消选择,c 清空选择,d 删除已选会话。序号支持空格、逗号和 1-3 形式的范围。
--provider 用来选择要管理的工具,可填写 codex、claude、opencode 或 cursor。列表、搜索、项目和统计命令还可以使用 all 汇总多个数据源。
| 用途 | 命令 |
|---|---|
| 查看完整帮助 | cc-sessions --help |
| 查看最近会话 | cc-sessions list --limit 20 |
| 查看 OpenCode 会话 | cc-sessions --provider opencode list --limit 20 |
| 查看 Cursor 会话 | cc-sessions --provider cursor list --limit 20 |
| 只看子代理会话 | cc-sessions --provider codex list --subagent |
| 按项目查看并包含归档会话 | cc-sessions --provider codex projects --archived |
| 搜索 Claude Code 对话 | cc-sessions --provider claude search "关键词" |
| 按项目查看会话 | cc-sessions --provider codex projects |
| 预览会话 | cc-sessions preview <会话文件> --limit 40 |
| 查看完整事件 | cc-sessions preview <会话文件> --mode all --limit 40 |
| 创建备份 | cc-sessions backup create --backup-dir ./backups --id <session-id> --name my-backup |
| 导出会话包 | cc-sessions bundle export --out-dir ./bundles --id <session-id> |
| 导入 OpenCode 会话包 | cc-sessions --provider opencode bundle import --src-dir ./bundles --mode overwrite --strict |
| 把 Cursor 会话转成 Claude Code | cc-sessions --provider cursor convert <定位符> --to claude |
| 检查 Codex 索引问题 | cc-sessions repair diagnose --json |
| 诊断 Cursor 数据库残留 | cc-sessions repair cursor-residue |
| 清理 Cursor 数据库残留 | cc-sessions repair cursor-residue --prune --kinds orphan_records,orphan_blobs --dry-run |
| 启动本地 Web UI | cc-sessions webui --host 127.0.0.1 --port 17888 |
CLI 默认读取与桌面版相同的数据位置。需要指定其他目录时,可以使用 --codex-dir、--claude-dir、--opencode-dir 或 --cursor-dir。
清理 Cursor 残留时,--kinds 必须自己写明要清哪几类,去掉 --dry-run 才会真正执行。可选类别是 empty_sessions、orphan_records、orphan_blobs、orphan_subagents、missing_project,后两类会丢对话。Cursor 的会话没有单独的文件路径,convert 和 preview 需要的定位符可以用 cc-sessions --provider cursor --json list 从 rollout_path 字段取。
list、search 和 projects 默认显示主会话。加入 --subagent 后只显示子代理会话。list 和 search 支持 --sort size,可以按会话大小排序。
preview 默认显示对话内容。--mode all 会加入过程消息、工具事件和元数据,--summary 输出一行摘要,--raw 输出筛选后的原始记录,--all 或 --limit 0 会读取到结尾。需要脚本处理结果时,可以加入 --json。
在 Windows 中读取 WSL 里的 Codex 数据:
cc-sessions --codex-dir "\\wsl.localhost\Ubuntu\home\me\.codex" list--codex-dir 始终填写 Codex 数据根目录(例如 ~/.codex),不要因为数据库在 ~/.codex/sqlite/state_5.sqlite 就改填 ~/.codex/sqlite。会话文件、config.toml 和索引仍从数据根目录读取。
数据库位置优先读取该根目录 config.toml 的 sqlite_home,其次是当前进程的 CODEX_SQLITE_HOME。未显式指定时,支持根目录和 sqlite/ 子目录两种布局;如果两处都有 state_5.sqlite,会提示先确认实际位置,不会猜测、移动数据库或创建空库。配置文件里的相对路径以该配置文件所在目录为基准。此解析不替代 Codex 的完整托管/项目配置加载。
Windows 可通过上述 WSL UNC 路径浏览数据,但服务商迁移和原生会话分支需要在同一个 WSL 发行版里运行 Linux 版 CC Sessions 与 Linux 版 Codex。Windows 版不会调用本机 Codex 去恢复 Linux 工作目录。若 WSL 中没有可运行的 codex,需先准备 Linux 版 Codex CLI 并确保 codex --version 正常,然后运行:
./cc-sessions --codex-dir "$HOME/.codex" list
./cc-sessions --codex-dir "$HOME/.codex" webui如果桌面应用的 WSL 引擎将配置/会话和数据库分开存储,应分别指定两处实际路径,而不是默认使用 WSL 的 ~/.codex:
export CODEX_HOME="/mnt/c/Users/<Windows用户名>/.codex"
export CODEX_SQLITE_HOME="/home/<WSL用户名>/.codex/sqlite"
./cc-sessions --codex-dir "$CODEX_HOME" list
./cc-sessions --codex-dir "$CODEX_HOME" webui以上路径仅为示例,以该引擎的实际环境为准。CC Sessions 的数据根需显式传入 --codex-dir;CODEX_HOME 本身不会覆盖其默认值或 WebUI 保存的路径。桌面应用可能已提供 Linux Codex,但需确认当前 PATH 找到的具体版本。0.167.0-alpha.4.1 等 alpha 版本不等同于 0.167.1,不会因版本解析修复而自动开启兼容迁移。
在浏览器打开终端显示的本地地址,确认列出的会话正确后,再执行服务商迁移。迁移启动的原生进程使用同一个 SQLite 目录,不会改写用户的 config.toml。
Codex 0.167.1 的服务商兼容迁移仅支持已关闭、未被原生进程持锁的 paginated 会话,包括普通、zstd 和 history_base 继承历史。操作会先备份,再由原生 Codex 保存目标服务商设置,成功前校验数据库与历史中的有效设置一致;不修改会话 ID、不新建分支。legacy 历史、未知版本或已加载会话不会使用此兼容写入。详细复现与验证范围见 scripts/provider-migration-validation.md。
cc-sessions webui --host 127.0.0.1 --port 17888服务默认只接受本机连接。它会为当前页面生成一次性访问令牌,并保存你在页面中设置的数据路径。
WSL2 通常可以通过 http://localhost:17888 访问。Web UI 仅允许回环监听(127.0.0.1、::1 或 localhost);远程访问请使用 SSH 隧道,不支持直接绑定 0.0.0.0 或局域网地址。API token 用于跨站防护,不是网络用户认证。
正式 CLI 包只从可执行文件旁的 dist/ 或 webui/ 加载界面,不会自动使用当前项目目录中的网页。开发时可用 CC_SESSIONS_WEBUI_DIST 显式指定受信任的构建目录;启动时会显示实际资源路径。
官方 CLI 包含 cc-sessions.portable 标记,设置保存在程序旁的 cc-sessions-webui-settings.json。自行构建且没有该标记时,设置会保存在当前系统的用户配置目录。环境变量 CC_SESSIONS_WEBUI_SETTINGS 可以指定其他设置文件。
| 场景 | 快捷键 | 作用 |
|---|---|---|
| 全局 | Ctrl / Cmd + K | 聚焦搜索框 |
| 全局 | Ctrl / Cmd + B | 展开或收起侧边栏 |
| 全局 | Ctrl / Cmd + Shift + L | 切换明暗主题 |
| 会话列表 | Delete / Backspace | 删除已选会话 |
| 会话预览 | Home | 回到已加载内容顶部 |
| 会话预览 | End | 到达底部并继续加载 |
| 会话预览 | Page Up | 向上翻页 |
| 会话预览 | Page Down | 向下翻页并按需加载 |
输入框、文本框和弹窗打开时,全局快捷键不会触发。预览滚动快捷键只在预览窗口内生效。
CC Sessions 默认从哪里读取会话?
Codex 默认读取 ~/.codex,Claude Code 默认读取 ~/.claude,OpenCode 读取当前安装使用的 opencode.db。Cursor 读取用户数据目录下的 globalStorage/state.vscdb(macOS 在 ~/Library/Application Support/Cursor/User,Windows 在 %APPDATA%\Cursor\User,Linux 在 ~/.config/Cursor/User),另外还会读取 ~/.cursor/chats 里 cursor-agent 命令行产生的会话。实际路径可以在设置页查看和修改,CLI 也可以通过目录参数覆盖。
会话包和 Markdown 导出有什么区别?
会话包用于备份和迁移,可以再次导入 CC Sessions。Markdown 适合阅读、归档或分享文本,不用于恢复原会话。
导出页面为什么比会话列表多一条或多几条?
导出页面面向备份和迁移,会列出更完整的底层记录。普通列表可能隐藏已归档会话、子代理会话,或把同一组 Codex 分支折叠成一个入口。归档记录会在导出页显示“已归档”徽标,仍可手动勾选并导出。
归档会删除会话吗?
不会。Codex 会把归档会话放到单独的归档目录,OpenCode 会记录归档时间。取消归档后,会话会重新出现在普通列表中。
归档视图里的“归档来源”是什么意思?
Codex 归档视图会按归档来源分组:我的归档(手动归档,以及没有来源标识的归档)、切换模型服务时自动归档的同步分支、备份恢复或会话包导入产生的迁移记录。来源记录保存在 CC Sessions 自己的数据里,不会改动会话文件。旧版本升级后已有的归档可能没有来源记录,可以在修复工具里用“补全归档来源标记”补齐(切换模型服务产生的克隆分支会自动识别为同步归档)。
OpenCode 本身有归档功能吗?
有。OpenCode 官方客户端提供归档操作,并把归档时间保存为会话状态。CC Sessions 使用的是这项原生状态,不是另外创建的标签。可以查看 OpenCode 官方源码中的 归档操作 和 会话状态定义。
移动会话目录后还能继续对话吗?
可以。CC Sessions 会同步更新会话和项目之间的关联,并在完成后检查结果。Claude Code 的相关会话文件和历史记录会一起处理,OpenCode 的子会话也会跟随主会话移动。这个功能不会移动你的项目源码,只会调整会话数据。建议移动前先创建备份。
Linux / macOS 上迁移 Claude 会话前,请退出 Claude Code,包括后台及 IDE 中的 Claude 会话,完成前不要重新启动。迁移会检查进程和全部相关文件的写入占用;无法完成检查时不会继续。Linux 需要安装 lsof(Debian / Ubuntu 可运行 sudo apt install lsof),macOS 使用系统自带工具。检查属于离线迁移的活动协调,不是 Claude 原生会遵守的排他锁;源副本和恢复清单仍会保留,不按时间自动删除,以免丢失旧句柄的晚到写入。活动会话可优先使用客户端支持的原生 /cd 功能。
跨机器导入时,项目路径不一样怎么办?
桌面版和自带网页界面会显示来源路径,可以把它映射到新电脑上的目录。直接使用命令行导入会保留会话包中的原路径,因此路径不同的情况更适合使用带界面的导入页面。
为什么看不到旧版 OpenCode storage 目录里的会话?
CC Sessions 读取当前 OpenCode 使用的数据库,不会把旧版 storage/ JSON 与当前数据混在一起。如果旧会话还没有迁入当前 OpenCode,请先用 OpenCode 自身提供的方式处理。
为什么修改 Cursor 会话前一定要退出 Cursor?
Cursor 把会话状态缓存在内存里,退出或空闲时才写回数据库。它在运行时改数据库,改动很可能被它按内存中的旧状态覆盖回去,反而更容易出问题。所以 CC Sessions 检测到 Cursor 在运行时会直接拒绝写入,而不是先改了再看运气。后台进程也要一起退出。
Cursor 数据库为什么会有几个 GB?清理安全吗?
Cursor 删除会话时只清掉一部分数据,检查点、代码差异、文件快照这些会留在库里,而且没有回收机制,用久了就会积压。
清理只删已经没有会话的记录:按会话归属的数据看它的会话头还在不在,按内容存放的数据则重新算一遍还有没有会话引用得到。判定用的是宽松口径,宁可多留也不会误删;扫描中只要有一处读不出来,那一类就整体跳过。仍然建议清理前先创建备份。
清理完还要点“压缩数据库”,磁盘占用才会真正回落。
Cursor 的子会话为什么在列表里看不到?
Cursor 的子会话由主会话持有引用,单独删掉会让主会话指向一个已经不存在的会话。所以它们不在列表里单独出现,只跟着主会话管理,删除主会话时一并删除。如果一个子会话同时被删除范围之外的另一个主会话引用,它会被保留。
可以把 Claude Code 或 Codex 的会话转成 Cursor 会话吗?
不可以,只能反过来。Cursor 编辑器内的会话没有命令行入口,就算写进它的数据库也没法从命令行打开继续聊。Cursor 会话可以转成 Claude Code 或 Codex 会话,转完用 claude --resume 或 codex resume 就能接着聊。
CC Sessions 会管理 Codex Memory 吗?
不会。Codex 自己负责本地 Memory 的生成和生命周期。CC Sessions 只提供 Claude Code 项目 Memory 的文件管理。Codex 的说明见 Codex Memories 官方文档。
Windows 提示“已保护你的电脑”怎么办?
请先确认文件来自本项目的 Releases。确认无误后,可以在提示窗口中选择“更多信息”,再选择继续运行;如果文件来源不明,请取消运行。
macOS 提示应用无法打开怎么办?
如果系统阻止未签名应用,可以在确认文件来自本项目 Release 后移除隔离标记:
xattr -d com.apple.quarantine "/Applications/CC Sessions.app"Codex 会话未收录到索引,为什么在官方 App 里仍然可见?
session_index.jsonl 的收录状态不等同于 Codex App 的实际可见性。修复页分别检查会话文件、索引和 threads 数据库记录;“修复会话索引”只重建 session_index.jsonl,“重建会话索引表”只更新数据库记录,都不会调整 Desktop 项目归属,也不要求先退出 Codex App。官方 App 的显示还受到服务商和归档状态等因素影响。
Codex 如何迁移到当前服务商?
会话列表和修复页默认原地迁移:自动备份后调用已安装 Codex App / CLI 的原生恢复接口,保留会话 ID、消息和已有分支,不再自动 Fork,也不需要常驻路由服务。旧格式与分页会话使用相同入口,按实际接口能力和迁移结果校验,不限制特定客户端版本号。
请先停止目标会话生成,迁移后重新打开该会话;如果 Codex App 仍缓存旧服务商连接,再退出并重开 App。迁移不会修正服务商地址、登录状态或模型兼容性。已有分支不会自动合并或删除,共享历史的删除保护继续保留。
迁移前备份保存在所选 Codex 目录的 backups/provider-migrations/,结果中返回具体备份路径;需要时可在备份页选择该目录恢复。失败时保留备份和迁移状态,响应中断后会重新读取确认,不覆盖期间新增的历史。
CLI 的 repair clone 和 repair batch-clone 未指定 --strategy 时默认使用 follow(原地迁移)。显式指定 scatter 或 continuous 仍沿用分支策略;需要独立副本可使用“完整 Fork”。
Codex App 开着时可以删除、移动或恢复会话吗?
可以。不会仅因 Codex App 正在运行就禁止操作。删除、移动、归档、覆盖导入/恢复和本地分支操作会检查实际受影响的会话:短暂比较所选会话的文件及线程记录,发现写入变化时停止操作并弹窗提示先停止该会话的生成或等待完成,不要求退出 App。检查不会为判断活跃状态扫描其他会话;分页会话还会检查线程记录当前指向的续写文件。
没有观察到写入不代表 agent 已停止:等待工具或网络时可能暂时没有新记录。因此仍保留提交前检查、文件指纹比对及事务处理;操作时请勿同时恢复目标会话的生成。App 运行期间不改写它缓存的私有项目配置,已打开的列表可能需要重启后刷新;移动等操作的 Desktop 项目归属是否同步会单独提示。
修复功能会改写会话正文吗?
Codex 修复主要处理本地索引和列表可见性,不会重写对话正文,也不能恢复已经删除的会话文件。Claude Code 的列表可见性修复可能会在文件末尾补充标题记录,执行前可以先打开“仅预览”查看报告。
Codex 会话按什么时间排序?
列表、时间分组和项目分组使用 Codex 记录的最近活动时间,精确到毫秒。只改变记录更新时间的操作不会让旧会话排到前面。卡片显示最近活动时间,悬浮提示中可查看与之不同的记录更新时间。
旧版数据库没有活动时间字段时,会回退到记录更新时间;没有数据库记录的归档会话则使用日志中的时间。
Codex 的 .jsonl.zst 会话文件可以读取吗?
可以。Codex 会把部分旧会话日志无损压缩为 .jsonl.zst,CC Sessions 支持读取、预览、搜索和分页历史,也会在数据库仍记录 .jsonl 路径时自动查找对应的压缩文件。备份和导出会生成普通 JSONL 副本,不解压或改写来源文件。
编辑消息、改写工作目录或向压缩分支同步内容时,会在取得 Codex 原生写入锁后自动恢复普通日志,无需先到 Codex 中续聊。转换保留会话 ID、消息字节与分页边界,同步当前线程和分支路径;原压缩文件保存在所选 Codex 目录的 backups/rollout-materializations/。正在写入、共享历史依赖和预览过期等原有检查继续生效。
为什么有些推理内容只能删除,不能修改?
Codex 的部分推理内容经过加密,Claude Code 的部分思考内容带有签名。改写这些数据会让原工具无法识别,因此 CC Sessions 只允许整段删除。
如果遇到无法读取、导入失败或迁移后无法继续对话,请到 GitHub Issues 提交问题,并附上操作系统、CC Sessions 版本、所管理的工具、复现步骤和完整错误信息。会话内容可能含有隐私,上传日志或截图前请先删除敏感信息。
- Node.js 20 或更高版本(前端 TypeScript 测试由
tsx运行) - npm
- Rust stable 工具链
- Tauri 2 对应平台的构建依赖
安装依赖并启动桌面开发环境:
npm ci
npm run tauri:dev常用检查:
npm run build
npm run cli:check
cargo test --manifest-path src-tauri/Cargo.toml --no-default-features --lib| 产物 | 命令 |
|---|---|
| 源码包 | npm run package:source |
| 桌面便携包 | npm run package:portable |
| 桌面安装器 | npm run package:product |
| 独立 CLI | npm run package:cli |
| 当前平台全部产物 | npm run package:all |
打包结果位于 release/,该目录不会提交到仓库。
发布前需要保持 package.json、package-lock.json、src-tauri/Cargo.toml、src-tauri/Cargo.lock 和 src-tauri/tauri.conf.json 中的项目版本一致。推送版本 tag 后,GitHub Actions 会构建 Windows、Linux、macOS Apple Silicon 和 macOS Intel 产物。
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin main
git push origin vX.Y.Z- yeahfeng 提供了 WSL 分离数据库布局与 Codex Desktop 版本识别的问题报告,并参与了迁移修复的复现和回归测试(#58)。
- linux.do 社区提供了讨论、测试和问题反馈。
- codex-session-cloner 为会话修复和导入导出实现提供了参考。
- thful 参与了 Markdown 导出测试并反馈问题。
- firesahc 为对话预览、时间线和过程消息交互提供建议,并持续参与测试。
- L 站用户 fengtang 参与了会话编辑、删除和归档功能测试。
本项目使用 MIT License。
