我开源了 cc-session-migrate ：让 Claude Code 会话在多台机器之间自由迁移
内容提要
本文介绍开源工具cc-session-migrate（csm），用于解决Claude Code会话跨机器迁移的痛点。该工具支持跨机器会话迁移、集群管理和S3自动备份，采用Hub-and-Spoke架构，所有Agent仅出站连接。文中详述了安装步骤、集群搭建、会话迁移命令，并分享了开发中处理路径编码、跨机器路径不一致等技术问题。
延伸解读
架构选择：Hub-and-Spoke 的优势
csm 采用 Hub-and-Spoke 架构，所有 Agent 仅建立出站 WebSocket 连接，无需监听端口，从而规避了 NAT 穿透和防火墙配置问题。这种设计使得笔记本、台式机等位于内网或路由器后的设备，只要能访问服务器 IP 即可加入集群，降低了多机协作的部署门槛。
路径编码与重映射的坑
Claude Code 的会话目录编码是有损的，无法通过解码还原真实路径。csm 通过读取 JSONL 文件中的 cwd 字段获取源路径，并在迁移时通过 --project 参数指定目标路径，自动完成目录重命名和路径替换，确保会话在跨机器后能正确恢复。
使用注意事项
csm 的 session pull 支持 8 字符前缀匹配，但 claude --resume 必须使用完整的 UUID，否则会找不到会话。此外，history.jsonl 的格式必须严格符合 {sessionId, project, display, timestamp}，否则会导致恢复失败。用户需注意这些细节以避免操作失误。
Q&A
cc-session-migrate 是什么？它主要解决什么问题？
cc-session-migrate（简称 csm）是一个用 Go 编写的 CLI 工具，用于解决 Claude Code 会话数据只能存储在本地磁盘（~/.claude/）导致无法跨机器迁移的问题。它支持跨机器迁移会话、集群管理和 S3 自动备份，让开发者可以在多台机器之间无缝续接 Claude Code 会话。
cc-session-migrate 的架构是怎样的？为什么采用这种架构？
cc-session-migrate 采用 Hub-and-Spoke（中心辐射）架构，而不是 Mesh 架构。所有 Agent 只建立出站 WebSocket 连接，不需要监听端口，通过中心 Server 进行中继。这种架构避免了 NAT 穿透问题，使得在不同网络环境（如公司内网、家庭 Wi-Fi）的机器都能轻松加入集群。
如何安装 cc-session-migrate？
在 Linux 上，可以通过 git clone 仓库并运行 make build 和 sudo ./scripts/install.sh --local 安装。在 macOS 或 Windows 上，可以使用 go install github.com/bigwhite/cc-session-migrate@latest 安装，并建议设置别名 csm='cc-session-migrate'。
如何搭建 cc-session-migrate 集群？
首先在 Linux 服务器上启动 Server 模式：修改 /etc/cc-session-migrate/env 中的 CSM_AGENT_ROLE=server，然后启用 systemd 服务，并查看生成的 auth-token。然后在笔记本等 Agent 机器上运行 csm agent --server-addr <服务器IP>:9827 --auth-token <token> --name <节点名> 加入集群。最后用 csm cluster list 验证。
如何使用 cc-session-migrate 迁移 Claude Code 会话？
使用 csm session list 查看本地会话，csm session list --node <节点名> 查看远程会话，然后使用 csm session pull --from <节点名> --project <本地项目路径> 拉取会话到本地。之后用 claude --resume <完整会话ID> 继续开发。注意 claude --resume 必须使用完整的 UUID，不支持前缀匹配。
cc-session-migrate 如何处理跨机器路径不一致的问题？
csm 在打包时会记录源路径，解包时通过 --project 参数指定目标路径，自动完成项目目录重命名（RenameProjectDir）、JSONL 文件内的路径替换（RemapPaths）以及 history.jsonl 记录更新，从而适配不同机器上的项目路径差异。
cc-session-migrate 支持哪些备份功能？
csm 支持将会话数据备份到 S3 兼容存储（如 Cloudflare R2、MinIO）。可以手动备份（csm backup create）、查看备份历史（csm backup list）、从备份恢复（csm backup restore）。守护进程模式下支持定时自动备份（增量，基于文件 mtime），并自动清理过期备份（默认保留 30 天）。
cc-session-migrate 的技术栈有哪些？
csm 使用 cobra + viper 作为 CLI 框架，WebSocket (gorilla) 进行通信，aws-sdk-go-v2 作为 S3 客户端，robfig/cron 进行定时任务调度，log/slog 作为日志库。整个项目零 CGO 依赖，支持交叉编译到 Linux、macOS 和 Windows。
