Claude Code 多端会话同步工具 —— 把历史会话（happy 托管 / VSCode 扩展 / 终端 CLI）无缝续接到当前对话，跨端、跨项目继承。
场景：你在终端 / VSCode / 手机上用 Claude Code 干了三天活，换了个会话、换了台设备——之前的进度"没了"。上下文是全新的，Claude 不记得上次做到哪。
事实：Claude Code 其实把每一次会话都完整记录在本机：
~/.claude/projects/<项目目录脱敏名>/<会话ID>.jsonl
痛点：这些记录散落在各项目、混存在工作台根存档、还有 happy 托管的会话——没有人把它们"翻出来"续接。
claude-code-sync 就是那把钥匙：一条 /同步 命令，把任何一段历史会话拉进当前对话，让 Claude 接着上次继续。
| 特性 | 说明 |
|---|---|
🈶 /同步 + /sync |
中文 / 英文双命令，效果完全相同 |
| 🗂️ 按项目归档 | 会话结束自动按内容识别所属子项目打标签，手动标签优先；按子项目 / 根项目列出会话 |
| 🔄 跨端继承 | happy 托管（手机 / 终端）↔ VSCode 扩展 ↔ CLI，全部支持 |
| 🪙 省 token 设计 | 先问作用域 → 只列标题 → 选中才读 → 压缩继承，绝不白读 |
| 🔒 全程只读 | 绝不修改任何会话存档（唯一可写的是工具自己的标签库） |
| ✂️ 自动截断 | --last N / --max-chars N，1.9MB 大存档也不爆上下文 |
Claude Code 每次对话都会把完整消息流追加写入一个文件：
~/.claude/projects/<sanitized-cwd>/<会话ID>.jsonl
- 每个项目目录一个文件夹，路径做了脱敏（全小写、
:/\→-） - 每次会话一个
.jsonl，一行一条消息 - happy 托管、VSCode、终端 CLI 全都落在这，靠
entrypoint字段区分来源端
用户敲 /同步 或 /sync
│
▼
┌─────────────────────────────┐
│ commands/sync.md 指挥剧本 │ Claude 读到这段 markdown，
│ （流程 + 硬约束 + 省token） │ 按剧本一步步执行
└──────────────┬──────────────┘
▼
┌─────────────────────────────┐
│ scripts/transcript-dump.mjs │ 只读解析 jsonl
│ scripts/tag-session.mjs │ 项目标签管理
└──────────────┬──────────────┘
▼
~/.claude/projects/ ← 数据源（只读）
~/.claude/sync-tags.json ← 标签库（工具自有）
commands/= 大脑的剧本（markdown，告诉 Claude 怎么做）scripts/= 干活的手（node 脚本，真正去读文件）- 命令文件用
${CLAUDE_PLUGIN_ROOT}定位自己的脚本，安装态 / 仓库态都可用
从工作站根目录（如
WorkSpace）启动 Claude Code 时，所有子项目的会话都混存在根存档；"进入子项目"只是概念切换、物理 cwd 不变，所以按目录归档无法区分归属。
解决方式：标签归档，默认按内容自动分类，手动标签优先。
会话结束（SessionEnd 钩子）──► 按内容识别所属子项目并打标签
│ （classify-session.mjs：路径证据权重2 + 用户提及权重1；
│ 闲聊 / 无关工作 → 根项目）
▼
"进入 snake-game"（可选）──► tag-session.mjs --set snake-game（manual，不被自动覆盖）
"回到工作台" ──► tag-session.mjs --clear（交还自动分类判定）
│
▼
/同步 先问作用域：哪个子项目 / 根项目？ → 按标签列出该项目的全部历史会话
标签存 ~/.claude/sync-tags.json（工具自有数据），与只读的会话存档完全分离——打标签不碰任何原始文件。历史会话可用 tag-session.mjs --retag [--dry-run] 一键重排。
第1步 问作用域 tag-session.mjs --projects → 列出已打标签的子项目
第2步 列标题 transcript-dump.mjs --list --tag <项目名> （只读标题，不读正文）
第3步 用户选 给会话ID 或 列表序号
第4步 压缩读取 --meta → --last 40 / --max-chars 20000 （自动定位存档）
第5步 无缝续接 概括上次进展，以"接着上次继续"推进
# 从 GitHub marketplace 安装
/plugin marketplace add produce123/claude-code-sync
/plugin install claude-code-sync@claude-code-sync或手动：claude plugin marketplace add https://github.com/produce123/claude-code-sync --scope user + claude plugin install claude-code-sync@claude-code-sync --scope user
claude plugin marketplace add "C:/你的路径/claude-code-sync" --scope user
claude plugin install claude-code-sync@claude-code-sync --scope user💡 已发布的
marketplace.json里source指向 GitHub。想纯本地安装（改源码、断网开发）时，临时把source改回"./."再安装即可。
⚠️ 本地安装是复制到缓存（~/.claude/plugins/cache/），改了源码需重装刷新：claude plugin uninstall claude-code-sync@claude-code-sync -s user -y claude plugin install claude-code-sync@claude-code-sync -s user -y新命令在下一个新会话生效。
复制本仓库到任意位置，进入目录启动 Claude Code，对它说：
"按 README.claude.md 自动配置这个插件"
它会自己完成校验、注册 marketplace、安装、验证。详见 README.claude.md。
node <本仓库路径>/scripts/transcript-dump.mjs --list
node <本仓库路径>/scripts/tag-session.mjs --projects# 列出当前项目所有会话（只列标题）
node scripts/transcript-dump.mjs --list
# 按项目标签列出会话（工作站模式）
node scripts/transcript-dump.mjs --list --tag <项目名>
# 手动打标签（manual，优先） / 自动分类单会话 / 全量重排（跳过手动标签）
node scripts/tag-session.mjs --set <项目名>
node scripts/tag-session.mjs --auto [--session <会话ID>]
node scripts/tag-session.mjs --retag [--dry-run]
# 列出已打标签的项目 / 列出全部标签
node scripts/tag-session.mjs --projects
node scripts/tag-session.mjs --list
# 读取某会话（自动按标签定位存档，无需 --project）
node scripts/transcript-dump.mjs <会话ID> --meta
node scripts/transcript-dump.mjs <会话ID> --last 40
node scripts/transcript-dump.mjs <会话ID> --max-chars 20000v0.3 起默认无需配置：会话结束时 SessionEnd 钩子（hooks/hooks.json）已按内容自动分类打标签。若想对「进入 / 退出」表达明确意图（不被自动分类覆盖），可在工作台根目录的 .claude/CLAUDE.md 加入：
用户说"进入 <项目>"时，同时执行：
node <本仓库路径>/scripts/tag-session.mjs --set <项目名>
用户说"回到工作台"时：
node <本仓库路径>/scripts/tag-session.mjs --clear这样 /同步 就能自动按项目归档你的所有会话。
claude-code-sync/
├─ .claude-plugin/
│ ├─ plugin.json ← 插件清单（manifest）
│ └─ marketplace.json ← 插件市场清单（发布 GitHub 用）
├─ commands/
│ ├─ 同步.md ← /同步 命令入口（中文别名）
│ └─ sync.md ← /sync 命令入口（英文主命令）
├─ hooks/
│ └─ hooks.json ← SessionEnd 钩子（会话结束自动打标签）
├─ scripts/
│ ├─ transcript-dump.mjs ← 核心工具（只读解析会话存档）
│ ├─ tag-session.mjs ← 项目标签管理（唯一会写文件）
│ ├─ classify-session.mjs← 按内容识别所属子项目（路径+提及证据）
│ └─ on-session-end.mjs ← 钩子入口：spawn 分离子进程跑 --auto
├─ .claude/CLAUDE.md ← 项目提示词（开发约定）
├─ README.md ← 用户手册（本文件）
├─ README.claude.md ← Claude Code 自动配置指引
└─ package.json
- 存档只读：绝不写入 / 修改 / 删除
~/.claude/projects/下任何.jsonl，也绝不改动~/.happy/下的任何文件（sessions.json、密钥、日志等）。 - 唯一可写文件：
~/.claude/sync-tags.json—— 工具自有标签库，仅tag-session.mjs（--set/--auto/--retag）写入。 - 续接 ≠ 修改：
/同步的结果是"当前会话获得历史认知"，不修改原存档；不透露 happy 存档中的加密密钥或敏感元数据。
- v0.3（当前）：本机会话继承 —— 读取本机
~/.claude/projects/缓存，跨端（happy/VSCode/CLI）与同端继承；工作站标签按内容自动分类（SessionEnd 钩子），手动标签优先。 - v2（规划）：跨机器 / 远端同步 —— 从 happy 托管拉取远端会话，需网络服务。
- 已发布：
marketplace.json里插件source已是真实仓库 URL，可直接通过 GitHub marketplace 安装。
MIT © produce123