skip to content

Resume, Branch & Export

Sessions as saved JSONL transcripts: continue the latest, resume by ID or name, branch with /branch or --fork-session, and export. Asked because resume restores history and mode but not launch flags.

part ofClaude Coderead it →
on this pageshow

explore

questions

4

In Claude Code, when do you use `claude -c`, `claude -r <name>` and `claude -r` with no argument to return to earlier work?

level: juniorimportance: must knowfreq 30%

answer

  1. latest versus a specific one
  2. scoped to the current directory
  3. names come from -n or /rename
  4. no argument opens a searchable list
  5. ambiguous name falls back to the list

basics

~20 s

claude -c reopens the most recent conversation in the current directory; claude -r with a name or session ID resumes that one session directly; claude -r alone opens the interactive session picker to search, preview and choose.

solid answer

~40 s

Claude Code saves every conversation continuously as a transcript tied to the project directory, so exiting or running `/clear` loses nothing. `claude -c` (`--continue`) picks the latest conversation in the current directory, skipping `claude -p`, Agent SDK and `/loop`-first sessions. `claude -r <name>` (`--resume`) resumes the session with that exact name directly, even from another worktree of the repository; an ambiguous name opens the picker pre-filled with it. A session ID works from any directory, and an absolute `.jsonl` transcript path works too. `claude -r` alone opens the picker: `Space` previews, `Ctrl+R` renames, `Ctrl+W` and `Ctrl+A` widen to all worktrees or all projects, `Ctrl+B` filters to the current branch. Inside a running session, `/resume` does the same job. Name sessions with `claude -n` or `/rename` when you juggle several tasks.

go deeper

for a junior

Know the three entry points cold: -c for the latest conversation here, -r with a name or ID for a specific one, -r alone for the picker. Name sessions with -n so resuming by name works.

for a middle

Explain the edges: -c is per directory and skips -p, SDK and sessions begun with /loop; an ambiguous name opens the picker from the CLI but errors from /resume; the default display name is not a handle.

for a senior

Show you can find any session: ID lookup across projects, the absolute .jsonl path, widening the picker with Ctrl+W and Ctrl+A, and --from-pr for work tied to a pull request.

for a principal

Frame naming as a team habit: one named session per task keeps parallel work findable, and retention settings decide how far back anyone can resume at all.

## Sessions are saved transcripts tied to a directory Claude Code writes every conversation to a local transcript file **continuously** as you work, and files it under the project directory you started in. Exiting, closing the terminal or running `/clear` does not lose the conversation: it stays on disk and can be reopened later with its full history. A **session** can therefore be addressed three ways: by its **session ID** (a UUID), by a **name** or title, and by the **directory** it belongs to. The entry points below differ in which of those they use. ## The entry points | Command | What it does | Reach for it when | | :- | :- | :- | | `claude -c` / `--continue` | Reopens the most recent conversation in the current directory | You stepped away and want to carry on with the last thing you did here | | `claude -r <name>` / `--resume <name>` | Resumes the session with that name directly | You named the session and know which one you want | | `claude -r <session-id>` | Resumes that session, searching beyond the current project | You have the ID, for example from a script or a log | | `claude -r` alone | Opens the interactive **session picker** | You need to search, preview or widen the list | | `/resume [session]` | The same lookup or picker from inside a running session | You want to switch conversations without restarting | `--resume` also accepts the **absolute path** to a session's `.jsonl` transcript file in place of an ID. A session ID is looked up first in the current project directory and its git worktrees, then in every other project on the machine, and it resolves only when exactly one other project holds a transcript for it, so a hand-copied duplicate produces a not-found message rather than an arbitrary pick. ## How names work Resuming by name is only as good as your names. The ways a session gets one: - **At startup**: `claude -n auth-refactor` (long form `--name`) sets the display name, also shown in the terminal title. - **Mid-session**: `/rename auth-refactor` renames it and shows the name on the prompt bar; with no argument it generates a name from the conversation. - **In the picker**: highlight a row and press `Ctrl+R`. - **On plan accept**: accepting a plan in plan mode gives an unnamed session a title based on the plan. - **Generated title**: an unnamed session gets a short AI-generated summary of its first prompt, and that title works as a resume handle too. - **Default display name**: interactive sessions also get a label such as `my-app-3f` for listings of running sessions. It is **not** a resume handle; passing it to `--resume` finds nothing. Name lookup covers the current repository and its worktrees. With an exact match, both `claude --resume <name>` and `/resume <name>` resume directly, even when the session lives in another worktree. With an **ambiguous** name they differ: the CLI opens the picker with the name pre-filled as a search term, while `/resume <name>` reports an error and you run `/resume` without an argument to choose. ## Using the session picker By default the picker lists sessions from the current worktree plus sessions started elsewhere that added this directory with `/add-dir`. Each row shows the name or generated title, time since last activity, git branch and file size. The keys worth knowing: - `Up` / `Down` to move, `Enter` to resume, `Esc` to leave search or the picker - `Space` to preview a session's content before opening it - `/` or any printable character to search; pasting a pull or merge request URL finds the session that created it - `Ctrl+W` to widen to all worktrees of the repository, `Ctrl+A` to every project on the machine - `Ctrl+B` to filter to sessions from the current git branch Selecting a session from an unrelated project normally copies a `cd` and resume command to the clipboard instead of opening it in the wrong directory. `claude --from-pr <number>` opens the same picker pre-filtered to sessions linked to that pull request, which Claude Code records automatically when Claude creates the PR. ## What `-c` and the picker leave out Three kinds of session surprise people by not showing up: 1. Sessions created with `claude -p` or the Agent SDK are kept out of the picker and out of `claude -c`; resume one by passing its session ID to `claude --resume`. 2. Sessions whose **first** prompt was `/loop` are skipped by both; running `/loop` later in a conversation does not hide it. 3. Sessions older than the retention period (30 days unless `cleanupPeriodDays` says otherwise) are deleted by a silent background sweep and are simply gone. ## Choosing in practice 1. Same directory, one task, back from lunch: `claude -c`. 2. Several tasks in flight: start each with `claude -n <task>` and return with `claude -r <task>`; the name is the cheapest insurance against a picker full of look-alike titles. 3. Not sure which one: `claude -r`, type a few words, preview with `Space`. 4. Already inside a session: `/resume`, which switches this terminal to the other conversation. Whichever route you take, the resumed session reloads the conversation from its transcript; what else it brings back (model, permission mode, launch flags) is a separate question with its own rules.

  • What does `claude --from-pr 123` do, and how does a session get linked to a pull request?
    It opens the session picker filtered to sessions linked to that pull request. Claude Code links a session automatically when Claude creates the PR in it. The flag accepts a PR number, a GitHub or GitHub Enterprise PR URL, a GitLab merge request URL or a Bitbucket pull request URL, and pasting such a URL into the picker's search finds the same session.
  • Why might `claude -c` skip the `claude -p` run you made in this directory an hour ago?
    Because `claude --continue` and the picker deliberately leave out sessions created with `claude -p` or the Agent SDK, so scripted runs do not crowd out interactive work. The transcript still exists: pass its session ID to `claude --resume <session-id>` to open it interactively.
  • How do `claude --resume <name>` and `/resume <name>` behave differently when two sessions share the name?
    The CLI form opens the session picker with the name pre-filled as a search term, so you pick between the matches. The in-session `/resume <name>` reports an error instead; run `/resume` with no argument to open the picker. With an exact single match, both resume directly, even across worktrees.

  • claude -c resumes the last session from any project on the machine
  • claude -r always needs a session ID; names cannot be used
  • The default display name like my-app-3f works as a resume handle
  • Exiting or running /clear throws the previous conversation away
  • claude -c also reopens the last claude -p run in this directory
open as a page

You resume yesterday's Claude Code session with `claude -r flaky-test` and its MCP servers and extra directory are missing — what does a resume restore, and what must you pass again?

level: seniorimportance: must knowfreq 12%

basics

~20 s

A resume restores what the transcript saved: the full history, the model, the agent and, on terminal routes, the permission mode, with exceptions. Launch flags such as --mcp-config, --settings, --plugin-dir, --fallback-model and --add-dir are not saved, so pass them again.

open as a page

In Claude Code, how do `/branch` and `--fork-session` let you try a second approach without losing the first, and what does each carry over?

level: middleimportance: should knowfreq 14%

basics

~20 s

/branch copies the conversation so far into a new session and switches the running process into it; --fork-session does the same at launch with -c or -r. The original stays intact. Only /branch keeps Allow for this session grants, and neither copies your files.

open as a page

Where does Claude Code store session transcripts, how long does it keep them, and when do you use `/export` instead of reading the JSONL?

level: middleimportance: should knowfreq 9%

basics

~10 s

Transcripts are JSONL files at ~/.claude/projects/<project>/<session-id>.jsonl, kept 30 days by default (cleanupPeriodDays). Their format is internal, so use /export for a readable plain-text copy and documented interfaces for scripts.

open as a page