# Claude Code 会话管理

> Claude Code 会话命名、恢复、分支、导出、transcript 存储,以及 /clear、/resume、/branch、/cd、--continue、--resume 的关系。

URL: https://docs.passion8.cc/docs/claude-code/sessions
Language: zh-CN
Publisher: Passion8

Claude Code 的 session 是绑定到项目目录的保存对话。它会持续写入本地 transcript,所以你可以退出后恢复、从中间分支、或在多个任务之间切换。

## 恢复入口

| 入口 | 作用 |
| --- | --- |
| `claude --continue` / `claude -c` | 恢复当前目录最近一次会话 |
| `claude --resume` / `claude -r` | 打开 session picker |
| `claude --resume <name>` | 按你设置的名称恢复 |
| `claude --resume <session-id>` | 按 ID 恢复 |
| `/resume` | 在当前会话内切到另一个会话 |
| `/resume <name>` | 在当前会话内按名称切换 |
| `claude --from-pr <number>` | 找到与 PR 关联的会话 |

`claude -p` 和 Agent SDK 产生的非交互式会话通常不出现在 picker 里,但可以用 session ID 恢复。自动化用法见 [Headless 自动化](https://docs.passion8.cc/docs/claude-code/headless)。

## 命名会话

| 时机 | 做法 |
| --- | --- |
| 启动时 | `claude -n auth-refactor` |
| 会话中 | `/rename auth-refactor` |
| picker 中 | 高亮会话后按 `Ctrl+R` |
| plan 接受后 | Claude Code 可能按计划内容自动命名 |

命名适合并行任务。不要依赖默认显示名作为恢复句柄,需要稳定恢复就自己命名。

## Session picker 快捷键

| 快捷键 | 作用 |
| --- | --- |
| `↑` / `↓` | 上下移动 |
| `→` / `←` | 展开或收起分组 |
| `Enter` | 恢复选中会话 |
| `Space` | 预览会话内容 |
| `Ctrl+R` | 重命名 |
| `/` | 搜索 |
| `Ctrl+A` | 扩展到本机所有项目 |
| `Ctrl+W` | 扩展到当前仓库所有 worktree |
| `Ctrl+B` | 按当前 Git 分支过滤 |
| `Esc` | 退出 picker 或搜索模式 |

如果 session 在另一个无关项目里,picker 可能复制一条 `cd && claude --resume ...` 命令,而不是直接切过去。

## 分支与 fork

`/branch [name]` 会复制当前对话并切到新分支。原会话不变,你可以回去继续。

```text
/branch try-streaming-approach
```

命令行也可以从已有会话 fork:

```bash
claude --continue --fork-session
```

注意:

| 点 | 说明 |
| --- | --- |
| 权限 | “本会话允许”的审批不会自动继承到新分支 |
| 两个终端恢复同一 session | 消息会写进同一份 transcript,容易交错 |
| 只想撤回一点 | 优先用 `/rewind`,不是 branch |
| 要隔离文件改动 | 用 [`--worktree`](https://docs.passion8.cc/docs/claude-code/worktrees) 或 `/batch` |

## `/cd` 和 `/add-dir`

| 命令 | 作用 |
| --- | --- |
| `/cd <path>` | 把当前 session 移动到另一个工作目录 |
| `/add-dir <path>` | 增加可访问目录,但 session 仍留在原目录 |
| `--add-dir <path>` | 启动时额外授予目录访问 |

官方说明里 `/cd` 会尽量保留 conversation cache,新目录的 `CLAUDE.md` 会作为消息追加,而不是直接重建系统提示。移动后,session 会出现在新目录的 picker 中。多目录隔离开发见 [Worktrees 并行工作区](https://docs.passion8.cc/docs/claude-code/worktrees)。

## 导出和 transcript

| 需求 | 推荐方式 |
| --- | --- |
| 给人看完整对话 | `/export` |
| 脚本拿一次运行结果 | `claude -p --output-format json` |
| 对已有 session 追问并拿 JSON | `claude -p --resume <session-id> --output-format json "..."` |
| Hook 归档对话 | 读取 hook 输入里的 `transcript_path` |
| 产品里管理会话 | 用 Agent SDK |

transcript 默认在:

```text
~/.claude/projects/<project>/<session-id>.jsonl
```

这些 JSONL 是内部格式,版本可能变化。自动化最好用 `/export`、`claude -p --output-format json` 或 Agent SDK,不要强依赖内部字段。

## 清理与保留

| 配置 | 作用 |
| --- | --- |
| `CLAUDE_CONFIG_DIR` | 改变配置和 transcript 根目录 |
| `cleanupPeriodDays` | 控制本地 session 保留天数 |
| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 禁止写 prompt history |
| `--no-session-persistence` | 单次 `claude -p` 不写 session |
| `claude project purge [path]` | 清理某项目本地 Claude Code 状态 |

## 官方参考

- [Manage sessions](https://code.claude.com/docs/en/sessions.md)
- [CLI reference](https://code.claude.com/docs/en/cli-reference.md)
- [Checkpointing](https://code.claude.com/docs/en/checkpointing.md)
- [Worktrees](https://code.claude.com/docs/en/worktrees.md)