# Claude Code Session management

> Name, resume, branch, export, and store Claude Code sessions, including /clear, /resume, /branch, /cd, --continue, and --resume.

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

A Claude Code session is a saved conversation associated with a project directory. It continually writes a local transcript so you can resume after exiting, branch from an intermediate point, or switch between tasks.

## Resume entry points

| Entry point | Purpose |
| --- | --- |
| `claude --continue` / `claude -c` | Resume the most recent session in the current directory |
| `claude --resume` / `claude -r` | Open the session picker |
| `claude --resume <name>` | Resume by a name you assigned |
| `claude --resume <session-id>` | Resume by ID |
| `/resume` | Switch to another session from the current one |
| `/resume <name>` | Switch by name |
| `claude --from-pr <number>` | Find the session associated with a PR |

Non-interactive sessions from `claude -p` or the Agent SDK usually do not appear in the picker, but can be resumed by ID. See [Headless automation](https://docs.passion8.cc/en/docs/claude-code/headless).

## Name a session

| When | Action |
| --- | --- |
| At startup | `claude -n auth-refactor` |
| During a session | `/rename auth-refactor` |
| In the picker | Highlight a session and press `Ctrl+R` |
| After accepting a plan | Claude Code may name it from the plan |

Names help with parallel tasks. Do not rely on an automatically displayed name as a stable resume handle; assign one yourself.

## Session picker shortcuts

| Shortcut | Action |
| --- | --- |
| `↑` / `↓` | Move up/down |
| `→` / `←` | Expand/collapse groups |
| `Enter` | Resume the selected session |
| `Space` | Preview the conversation |
| `Ctrl+R` | Rename |
| `/` | Search |
| `Ctrl+A` | Include all projects on this machine |
| `Ctrl+W` | Include all worktrees of this repository |
| `Ctrl+B` | Filter by the current Git branch |
| `Esc` | Exit the picker or search |

For a session in an unrelated project, the picker may copy a `cd && claude --resume ...` command instead of switching directly.

## Branch and fork

`/branch [name]` copies the current conversation and switches to the new branch. The original stays intact and can be resumed.

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

Fork from the CLI with:

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

| Consideration | Detail |
| --- | --- |
| Permissions | Approvals limited to this session do not automatically carry into the branch |
| Two terminals on one session | Messages share a transcript and can interleave |
| Undoing a small detour | Prefer `/rewind` over branching |
| Isolating file changes | Use [`--worktree`](https://docs.passion8.cc/en/docs/claude-code/worktrees) or `/batch` |

## /cd and /add-dir

| Command | Purpose |
| --- | --- |
| `/cd <path>` | Move the current session to another working directory |
| `/add-dir <path>` | Add an accessible directory without moving the session |
| `--add-dir <path>` | Grant additional directory access at startup |

The official documentation describes `/cd` as preserving the conversation cache where possible. The new directory's `CLAUDE.md` is appended as a message rather than rebuilding the system prompt. The session then appears in the new directory's picker. See [Worktrees](https://docs.passion8.cc/en/docs/claude-code/worktrees) for isolated multi-directory development.

## Export and transcripts

| Need | Recommended approach |
| --- | --- |
| Share a full conversation with a person | `/export` |
| Get one run's result in a script | `claude -p --output-format json` |
| Follow up on an existing session as JSON | `claude -p --resume <session-id> --output-format json "..."` |
| Archive a conversation in a hook | Read `transcript_path` from hook input |
| Manage sessions in a product | Use the Agent SDK |

Default transcript path:

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

JSONL transcripts are an internal format that can change. Prefer `/export`, JSON print output, or the Agent SDK rather than depending on internal fields.

## Cleanup and retention

| Setting | Purpose |
| --- | --- |
| `CLAUDE_CONFIG_DIR` | Change the configuration and transcript root |
| `cleanupPeriodDays` | Set local session retention in days |
| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | Disable writing prompt history |
| `--no-session-persistence` | Do not save a session for this `claude -p` run |
| `claude project purge [path]` | Remove a project's local Claude Code state |

## Official references

- [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)