Claude Code 深度学习手册

主题

管理会话 Sessions ​

命名、resume、branch、切换 Claude Code 会话，绑定到项目目录本地保存。

是什么 ​

会话（session）是绑定到某个项目目录的已保存对话。Claude Code 在你工作时持续把它保存到本地，因此可以退出或运行 /clear 后从中断处继续、分支出去尝试另一种思路，或在多个任务间切换。

桌面应用、Claude Code on the web、VS Code 扩展各自维护独立的会话历史；本模块讲的是 CLI。会话按项目目录分别存储。

怎么工作 ​

  • Resume（恢复）：会话持续写入本地 transcript 文件。入口有 claude --continue（恢复当前目录最近一次会话）、claude --resume（打开 session picker）、claude --resume <name>（按名直接恢复）、claude --from-pr <number>（恢复关联某 PR 的会话）、以及会话内的 /resume。
  • 用 claude -p 或 Agent SDK 创建的会话不出现在 picker 里，但仍可用 claude --resume <session-id>（传 session ID）恢复。
  • Name（命名）：可在启动时 claude -n <name>、会话中 /rename <name>、picker 中高亮后按 Ctrl+R；plan mode 接受 plan 时若未命名会用 plan 内容自动命名。
  • Session picker：会话内 /resume 或无参数的 claude --resume 打开。默认显示当前 worktree 的会话，Ctrl+W 扩到本仓库所有 worktree，Ctrl+A 扩到本机所有项目，Ctrl+B 按当前 git 分支过滤；可粘贴 GitHub/GitLab/Bitbucket 的 PR/MR URL 来找到创建它的会话。
  • Branch（分支）：复制当前对话并切入副本，原会话保持不变。会话内 /branch [name]，或命令行用 --continue/--resume 配合 --fork-session。
  • Export/定位：/export 把当前对话复制到剪贴板或存为纯文本文件。transcript 以 JSONL 存于 ~/.claude/projects/<project>/<session-id>.jsonl。
  • 会话内管理上下文：/clear（清空并保存可恢复的旧对话）、/compact [instructions]（用摘要替换历史）、/context（查看当前上下文占用）。

怎么配置 / 用法 ​

bash
# 恢复
claude --continue                 # 恢复当前目录最近会话
claude --resume                   # 打开 session picker
claude --resume <name>            # 按名/ID 直接恢复
claude --from-pr <number>         # 恢复关联该 PR 的会话

# 命名
claude -n auth-refactor           # 启动时命名
/rename auth-refactor             # 会话中重命名

# 分支
/branch try-streaming-approach    # 会话内分支
claude --continue --fork-session  # 命令行分支

# 导出
/export                           # 复制/保存当前对话

session picker 快捷键：↑/↓ 导航、→/← 展开或折叠分组、Enter 恢复、Space 预览、Ctrl+R 重命名、Ctrl+A 全项目、Ctrl+W 全 worktree、Ctrl+B 按 git 分支过滤、Esc 退出。transcript 默认 30 天后清理，用 cleanupPeriodDays 修改；自定义存储位置设 CLAUDE_CONFIG_DIR。

什么时候用 ​

  • 退出或 /clear 后想从上次中断处继续工作
  • 并行处理多个任务，需要给会话命名以便后续查找和恢复
  • 想在不丢失当前路径的前提下尝试另一种实现思路（branch）
  • 需要恢复某个 PR/MR 相关的会话，或导出对话存档

限制 / 坑 ​

  • 用 claude -p（headless）或 Agent SDK 创建的会话不出现在 session picker 中，只能用 session ID 恢复
  • 分支后用 allow for this session 批准过的权限不会带到新分支
  • 不分支地在两个终端恢复同一会话时，两边消息会交错进同一份 transcript
  • 本地 transcript 文件默认 30 天后被删除（由 cleanupPeriodDays 控制）

硬事实速查（12 条） ​

  • 会话是绑定到项目目录、随工作持续本地保存的对话，按项目目录分别存储
  • 桌面应用、Claude Code on the web、VS Code 扩展各自维护独立的会话历史
  • claude --continue 恢复当前目录最近会话；claude --resume 打开 picker；claude --resume <name> 按名直接恢复
  • claude --from-pr <number> 可恢复关联某 PR 的会话
  • 按名恢复在当前仓库及其 worktree 间解析；名称歧义时 claude --resume <name> 打开预填该名的 picker，/resume <name> 歧义时报错
  • 命名方式：启动 claude -n、会话中 /rename、picker 中 Ctrl+R、plan mode 接受 plan 时自动命名
  • /branch [name] 或命令行 --fork-session 创建对话副本，原会话保持不变
  • /branch、/rewind、--fork-session 创建的 fork 会话在 picker 中归组于其根会话下，按 → 展开
  • picker 默认显示当前 worktree 会话，Ctrl+W 扩到全 worktree、Ctrl+A 扩到全机项目、Ctrl+B 按 git 分支过滤
  • 可在 picker 搜索中粘贴 GitHub/GitHub Enterprise/GitLab/Bitbucket 的 PR/MR URL 定位创建它的会话
  • transcript 为 JSONL，路径 ~/.claude/projects/<project>/<session-id>.jsonl；设 CLAUDE_CONFIG_DIR 可改存储位置
  • 非交互模式 --no-session-persistence 可完全禁止写 transcript

官方出处：https://code.claude.com/docs/en/sessions