claude-session-restore

找回 Claude 桌面 App 换账号后"消失"的 Claude Code 会话;也能把纯 CLI 会话注册进桌面 App 列表。纯本地操作、零依赖、每次写入前自动备份。

English

丢给 agent 之后会发生什么

agent 会按 AGENTS.md 一条命令非交互完成:自动备份 → 只拷未归档会话(已存在的和归档的都自动跳过)→ 提醒你重启桌面 App。全程不需要你确认,也不会看到一堆计划。供 agent 直接抓取的 raw 地址:https://raw.githubusercontent.com/heyroute-ai/claude-session-restore/main/AGENTS.md

问题在哪

在 Claude 桌面 App 里切换登录账号(比如一个账号额度用完了),Code 标签页的会话列表会整个清空——看起来对话全丢了。

其实一条都没丢。Claude Code 的对话正文(transcript)一直存在 ~/.claude/projects/ 下,与账号无关;丢的只是桌面 App 自己的会话注册表,它按账号目录隔离:

%APPDATA%\Claude\claude-code-sessions\        (Windows;macOS/Linux 路径见下表)
├── <旧账号uuid>/                              ← 旧账号:条目都在,只是 App 不再读这里
│   └── <workspace-uuid>/
│       ├── local_xxx.json                     ← 每个会话一个小指针文件
│       └── local_yyy.json                     ← "cliSessionId" 指向真正的对话记录
└── <新账号uuid>/                              ← 新账号:App 现在只读这里
    └── <workspace-uuid>/
        └── local_zzz.json

每个 local_*.json 只是一个指针:标题、时间戳,以及指向 ~/.claude/projects/<项目>/<cliSessionId>.jsonl(对话本体)的引用。把指针拷进新账号目录,会话就原样回到 App 列表,内容完整无缺。

对应的官方 issue:#48511(换账号丢历史)、#50891(CLI 会话不显示在 App)、#50067(App 里没有 /resume)。

手动快速开始

# 只读,看现状
npx claude-session-restore list

# 预览恢复计划(不写入任何东西)
npx claude-session-restore restore --dry-run

# 把失活账号的全部未归档会话恢复到当前账号
npx claude-session-restore restore

npx 会自动拉取已发布的 npm 包(带 provenance 溯源),无需预先安装。然后完全退出并重新打开桌面 App,会话就回来了。

命令

常用参数:--dry-run、--yes、--to-profile <名字>、--from-profile <名字>、--all-accounts、--from <账号前缀>、--to <账号前缀>、--sessions <id或标题片段,…>、--project <路径片段>、--include-archived、--force、--json、--registry <目录>、--claude-dir <目录>。

多 profile(同时登录多个账号)

用 --user-data-dir 可以让桌面 App 同时开多个互不干扰的实例,每个登录不同账号:

claude-desktop --user-data-dir="$HOME/.config/Claude-Profiles/account-b"

这样机器上就有多个注册表,而不只是一个。旧版本只认默认安装那一个,于是"账号 B 的会话还留在默认 profile 里、B 自己的窗口却看不到"这种情况完全没法处理。现在会自动发现它们:

npx claude-session-restore profiles          # 看看本机有哪些 profile
npx claude-session-restore restore --to-profile account-b --dry-run

restore 默认只从两类不可能混淆身份的来源取数据:

1. 同一 profile 内的其他账号目录 —— 经典的换账号场景。
2. 其他 profile 里相同 account uuid 的目录 —— 同一个账号被留在了别处。

想把别的账号的会话也扫进来,必须显式 --from-profile <名字> 或 --all-accounts。默认永远不会替你做这个决定。

restore 到底做了什么

1. 识别目标 profile及其活跃账号:优先读该 profile config.json 里的 lastKnownAccountUuid(权威值),读不到才退回"最近写入过哪个目录"的推断。可用 --to-profile / --to 覆盖。
2. 把目标 profile 的注册表备份到同级的 claude-code-sessions.backup-<时间戳>。
3. 把选中的 local_*.json 拷进目标 workspace 目录。跨账号时清空 bridgeSessionIds(它引用的是源账号名下的服务端会话);同一账号在两个 profile 之间搬运时保留该字段——身份没变,引用依然有效,清掉反而白丢状态。
4. 永不改动源目录、永不覆盖已存在条目(除非 --force)、永不碰 transcript。

回滚:删除拷入的 local_*.json,或整体还原备份目录。其余什么都没变。

路径

额外 profile 会在同一父目录下按 Claude* 前缀向下扫描两层,因此 <父目录>/Claude-Profiles/<名字> 这类布局能被自动发现;任意位置的目录可用 --profile <目录> 直接指名。

transcript 是全局共享的,不属于任何 profile——所有 profile 的会话正文都在同一个 ~/.claude/projects 下,这正是跨 profile 恢复之后内容依然完整的原因。transcript 位置遵循 CLAUDE_CONFIG_DIR;两个路径都可用 --registry / --claude-dir 按次覆盖。

注意与坑

• 恢复前建议先退出 App。条目本来就只在启动时加载,先退出还能排除 App 退出时改写状态的可能。
• 目标账号必须在 App 里开过至少一次会话(其注册表目录才存在);目录不存在时工具会拒绝执行而不是瞎猜。
• 注册表格式没有官方文档,随时可能变。当前结构基于 2026 年 7 月桌面版 2.1.x 的观察。doctor + 自动备份是安全网;最坏情况也只是 App 忽略拷入的文件。
• 恢复条目不会合并分叉:如果你还用 claude --resume 在终端里续过同一个会话,那条延续是独立的 transcript(可用 adopt 注册进 App)。
• 预防:额度用完时,在会话里直接 /login 原地切换账号——对话不中断,根本不会触发这个问题。

非目标

• 不联网、不上传、无遥测——只读写本机文件。
• 不处理 claude.ai 网页对话的导出;那个场景请用 Anthropic 官方的数据导出。

为什么配合 HeyRoute

HeyRoute 是稳定快速的开发者 API 服务:一个入口聚合 40+ 上游 AI 供应商,适合把 Claude Code、Codex 等 coding agent 与多模型工作流接到统一、可靠的 API 上。

经常在多个账号之间切换的重度 agent 用户,正是最容易碰到"换号丢会话"的人——用 HeyRoute 统一入口减少切换本身,用 claude-session-restore 兜底恢复。

立即访问:https://heyroute.ai/

声明

社区工具,与 Anthropic 无关联、未经其背书。它只在你自己的机器上、对你自己安装产生的本地文件做管理。风险自担;自动备份就是为此存在的。

许可证

MIT © HeyRoute contributors