Manage sessions changedsessions
Nearest release: v2.1.309, published 5 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 23 Oct 2026 02:09 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 23 Oct 2026 19:07 UTC.
Upstream edited
Recorded here
Lines+66added
Lines−66removed
From line
2
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits43to this page, all time
The whole hunk
from line 2, old and new numbered
/
from line 2
22
33> Name, resume, branch, and switch between Claude Code conversations. Covers `--continue`, `--resume`, `--from-pr`, the `/resume` picker, session naming, exporting transcripts, and where transcripts are stored.
44
5A [session](/docs/en/glossary.md#session) is a saved conversation tied to a project directory. Claude Code stores it locally as you work, so you can resume where you left off, branch to try a different approach, or switch between tasks.
5A [session](https://code.claude.com/docs/en/glossary.md#session) is a saved conversation tied to a project directory. Claude Code stores it locally as you work, so you can resume where you left off, branch to try a different approach, or switch between tasks.
66
7The [desktop app](/docs/en/desktop.md#work-in-parallel-with-sessions), [claude.ai/code](/docs/en/claude-code-on-the-web.md), and the [VS Code extension](/docs/en/vs-code.md#resume-past-conversations) each keep their own session list, and the desktop app can also [resume a CLI session](/docs/en/desktop.md#coming-from-the-cli). This page covers the CLI.
7The [desktop app](https://code.claude.com/docs/en/desktop.md#work-in-parallel-with-sessions), [claude.ai/code](https://code.claude.com/docs/en/claude-code-on-the-web.md), and the [VS Code extension](https://code.claude.com/docs/en/vs-code.md#resume-past-conversations) each keep their own session list, and the desktop app can also [resume a CLI session](https://code.claude.com/docs/en/desktop.md#coming-from-the-cli). This page covers the CLI.
88
99## Resume a session
1010
from line 21
2121
2222### Resume a running background session
2323
24When the conversation you resume with `claude --resume` or `/resume` belongs to a [background session](/docs/en/agent-view.md) that is still running, Claude Code opens the running session itself. With `--bg` on the command line, the resume is a [background dispatch](/docs/en/agent-view.md#from-your-shell) instead. Before v2.1.285, Claude Code refused and told you to open the session with `claude attach <id>`, or to stop it with `claude stop <id>` first.
24When the conversation you resume with `claude --resume` or `/resume` belongs to a [background session](https://code.claude.com/docs/en/agent-view.md) that is still running, Claude Code opens the running session itself. With `--bg` on the command line, the resume is a [background dispatch](https://code.claude.com/docs/en/agent-view.md#from-your-shell) instead. Before v2.1.285, Claude Code refused and told you to open the session with `claude attach <id>`, or to stop it with `claude stop <id>` first.
2525
26* **From your shell**: `claude --resume <session>` runs [`claude attach`](/docs/en/agent-view#attach-to-a-session) on that session in the same terminal instead of loading the transcript itself. A prompt you pass on the command line, as in `claude --resume <session> "check the tests too"`, goes to the session as its next turn first, and Claude Code prints `Sent your prompt to the background session (<id>); opening it…` before attaching. `claude -p --resume <session> "prompt"` typed at a terminal does the same, so `-p` doesn't keep that run non-interactive.
26* **From your shell**: `claude --resume <session>` runs [`claude attach`](https://code.claude.com/docs/en/agent-view#attach-to-a-session) on that session in the same terminal instead of loading the transcript itself. A prompt you pass on the command line, as in `claude --resume <session> "check the tests too"`, goes to the session as its next turn first, and Claude Code prints `Sent your prompt to the background session (<id>); opening it…` before attaching. `claude -p --resume <session> "prompt"` typed at a terminal does the same, so `-p` doesn't keep that run non-interactive.
2727
2828 Claude Code doesn't open the session when the command line has any of these:
2929
from line 32
3232 * Flags that read the output, such as `--output-format json` or `--json-schema`
3333 * Flags that limit or rewind the run, such as `--max-turns` or `--max-budget-usd`
3434
35 With any of these, or when [agent view is turned off](/docs/en/agent-view.md#turn-off-agent-view), Claude Code sends nothing and exits with status 1, printing that the session is running in the background along with the `claude attach <id>` command that opens it, or telling you to find it in `claude agents` when it can't determine the ID. Add `--fork-session` to resume a copy of the conversation instead. To continue the conversation itself in a session of your own, with your flags applied, run `claude stop <id>` and then repeat the command.
35 With any of these, or when [agent view is turned off](https://code.claude.com/docs/en/agent-view.md#turn-off-agent-view), Claude Code sends nothing and exits with status 1, printing that the session is running in the background along with the `claude attach <id>` command that opens it, or telling you to find it in `claude agents` when it can't determine the ID. Add `--fork-session` to resume a copy of the conversation instead. To continue the conversation itself in a session of your own, with your flags applied, run `claude stop <id>` and then repeat the command.
3636
3737 A prompt that starts with `/` or `!` isn't sent, and neither is any prompt while the session waits on your answer to a question. In both cases Claude Code doesn't open the session, and the message includes `Your prompt was not sent to it` with the reason.
3838* **From inside a session**: `/resume` moves your current conversation to the background and attaches this terminal to the running session, printing `Opening "<title>", running in the background (<id>)`. Press `←` on an empty prompt to return to agent view, which also lists the conversation you left. When the current conversation can't move to the background, for example because you're already attached to a background session or session persistence is off, `/resume` prints the `claude attach` command to run instead.
from line 41
4141
4242When Claude Code loads a conversation from its transcript, the resumed session restores the conversation along with the state saved in it:
4343
44* Conversation history: the messages, tool calls, and results. If the session was [compacted](/docs/en/context-window.md#what-survives-compaction), the conversation opens at a `Conversation compacted` row. Claude continues with the last compaction's summary, the messages that compaction left unsummarized, and every message since. The messages that the last compaction summarized aren't loaded again.
45* Interrupted tool calls: a tool that was still running when the previous process ended, for example in a crash, doesn't finish or get rerun when you resume. Claude sees the call marked as cut off before its result was recorded and is told to check whether it took effect before running it again, unless [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/en/env-vars#variables) is set.
46* Model: the session continues on the model it was using, except in the cases in [Setting your model](/docs/en/model-config.md#setting-your-model).
47* Agent: a session started with [`--agent`](/docs/en/sub-agents#invoke-subagents-explicitly) or the `agent` setting continues as that agent, keeping its tool restrictions and model. Pass `--agent` when resuming to pick a different one; for the system prompt in either case, see [System prompt flags in resumed conversations](/docs/en/cli-reference.md#system-prompt-flags-in-resumed-conversations). Claude Code looks for the agent in two places: the session's original directory, provided you have [trusted that workspace](/docs/en/permissions.md#project-allow-rules-and-workspace-trust), and then the directory you resume from, so a project-scoped agent still loads when you resume from another directory. If Claude Code doesn't find the agent in either place, the session resumes with the default tools and shows a [warning naming the agent](/docs/en/errors.md#session-agent-no-longer-available).
44* Conversation history: the messages, tool calls, and results. If the session was [compacted](https://code.claude.com/docs/en/context-window.md#what-survives-compaction), the conversation opens at a `Conversation compacted` row. Claude continues with the last compaction's summary, the messages that compaction left unsummarized, and every message since. The messages that the last compaction summarized aren't loaded again.
45* Interrupted tool calls: a tool that was still running when the previous process ended, for example in a crash, doesn't finish or get rerun when you resume. Claude sees the call marked as cut off before its result was recorded and is told to check whether it took effect before running it again, unless [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](https://code.claude.com/docs/en/env-vars#variables) is set.
46* Model: the session continues on the model it was using, except in the cases in [Setting your model](https://code.claude.com/docs/en/model-config.md#setting-your-model).
47* Agent: a session started with [`--agent`](https://code.claude.com/docs/en/sub-agents#invoke-subagents-explicitly) or the `agent` setting continues as that agent, keeping its tool restrictions and model. Pass `--agent` when resuming to pick a different one; for the system prompt in either case, see [System prompt flags in resumed conversations](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags-in-resumed-conversations). Claude Code looks for the agent in two places: the session's original directory, provided you have [trusted that workspace](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust), and then the directory you resume from, so a project-scoped agent still loads when you resume from another directory. If Claude Code doesn't find the agent in either place, the session resumes with the default tools and shows a [warning naming the agent](https://code.claude.com/docs/en/errors.md#session-agent-no-longer-available).
4848* Permission mode: if you resume from a terminal with `claude --continue`, `claude --resume <session-id>`, or `claude --resume <name>` when the name matches one session, without `-p`, Claude Code restores the permission mode the session was in, except in the cases in [permission mode on resume](#permission-mode-on-resume), which also covers the session picker, `/resume`, and resuming with `claude -p`. Pass `--permission-mode` or `--dangerously-skip-permissions` to override the restored mode.
49* Active goal: a [goal](/docs/en/goal.md#resume-with-an-active-goal) that was still active when the session ended carries over; its turn count, timer, and token-spend baseline reset.
50* Session-scoped scheduled tasks: [tasks that haven't expired](/docs/en/scheduled-tasks.md#limitations) are restored. Background Bash and monitor tasks aren't.
51* Background work: a [background subagent](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background), background Bash command, or [workflow](/docs/en/workflows.md) that ended with the previous process shows up in the resumed transcript as a note that it didn't finish. Claude Code doesn't start a turn from those notes; Claude reads them with your next prompt.
49* Active goal: a [goal](https://code.claude.com/docs/en/goal.md#resume-with-an-active-goal) that was still active when the session ended carries over; its turn count, timer, and token-spend baseline reset.
50* Session-scoped scheduled tasks: [tasks that haven't expired](https://code.claude.com/docs/en/scheduled-tasks.md#limitations) are restored. Background Bash and monitor tasks aren't.
51* Background work: a [background subagent](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background), background Bash command, or [workflow](https://code.claude.com/docs/en/workflows.md) that ended with the previous process shows up in the resumed transcript as a note that it didn't finish. Claude Code doesn't start a turn from those notes; Claude reads them with your next prompt.
5252
53Not every configuration flag from the original launch is restored. If the session depended on `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model`, or directories added with `--add-dir`, pass them again when you resume; directories added mid-session with `/add-dir` aren't restored either, though the session picker still uses them to locate the session. The standard settings files, such as `settings.json` and `settings.local.json`, are re-read at launch, so configuration that lives in them doesn't need to be passed again. For `--system-prompt` and `--append-system-prompt`, see [System prompt flags in resumed conversations](/docs/en/cli-reference.md#system-prompt-flags-in-resumed-conversations).
53Not every configuration flag from the original launch is restored. If the session depended on `--mcp-config`, `--settings`, `--plugin-dir`, `--fallback-model`, or directories added with `--add-dir`, pass them again when you resume; directories added mid-session with `/add-dir` aren't restored either, though the session picker still uses them to locate the session. The standard settings files, such as `settings.json` and `settings.local.json`, are re-read at launch, so configuration that lives in them doesn't need to be passed again. For `--system-prompt` and `--append-system-prompt`, see [System prompt flags in resumed conversations](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags-in-resumed-conversations).
5454
5555#### Permission mode on resume
5656
from line 58
5858
5959* Terminal: `claude --continue`, `claude --resume <session-id>`, or `claude --resume <name>` when the name matches one session, without `-p`. Claude Code restores the permission mode the session was in, except in the cases in the table. Pass `--permission-mode` or `--dangerously-skip-permissions` to override the restored mode.
6060* Non-interactive: `claude -p --resume` or `claude -p --continue`. Claude Code starts the run in the permission mode a new `claude -p` run would start in, except that a session that ended in plan mode resumes in plan mode under the [conditions below](#resume-in-plan-mode-with-p).
61* VS Code: the extension's conversation panel. The table covers only a conversation that ended in plan mode; for the rest, see [resume past conversations](/docs/en/vs-code.md#resume-past-conversations).
61* VS Code: the extension's conversation panel. The table covers only a conversation that ended in plan mode; for the rest, see [resume past conversations](https://code.claude.com/docs/en/vs-code.md#resume-past-conversations).
6262* Session picker at launch: a session you select from the [session picker](#use-the-session-picker), whether you opened it with `claude --resume` alone, `claude --from-pr`, or a name that matches more than one session. Claude Code starts the session in the permission mode it would start a new session in from the same command line, except that a session that ended in plan mode resumes in plan mode. If you pass `--permission-mode`, `--dangerously-skip-permissions`, or `--fork-session`, Claude Code doesn't restore plan mode. No other stored permission mode is restored.
6363* `/resume` inside a session, with or without an argument: the conversation you switch to continues in the permission mode your current session is in, except that a conversation that ended in plan mode resumes in plan mode, even if you launched Claude Code with `--permission-mode` or `--dangerously-skip-permissions`. If that conversation was already open earlier in this run of Claude Code, such as the conversation you started in or one you left with `/clear` or `/resume`, it continues in your current permission mode instead.
6464
65If a [deny rule](/docs/en/permissions.md#manage-permissions) removes the [`ExitPlanMode`](/docs/en/tools-reference) tool, Claude can't present a plan for approval, so Claude Code doesn't restore plan mode. The session starts in the permission mode a new session would start in from the same command line. With `/resume`, the conversation continues in your current permission mode.
65If a [deny rule](https://code.claude.com/docs/en/permissions.md#manage-permissions) removes the [`ExitPlanMode`](https://code.claude.com/docs/en/tools-reference) tool, Claude can't present a plan for approval, so Claude Code doesn't restore plan mode. The session starts in the permission mode a new session would start in from the same command line. With `/resume`, the conversation continues in your current permission mode.
6666
6767Restoring plan mode on the non-interactive and VS Code paths requires Claude Code v2.1.246 or later. Each row names the permission mode the session ended in, which of the terminal, non-interactive, and VS Code paths you resume it by, and the permission mode Claude Code starts the resumed session in.
6868
6969| Session ended in | How you resume | Permission mode after you resume |
7070| :- | :- | :- |
71| `bypassPermissions` | Terminal | The permission mode a new session would start in. To [bypass permissions](/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) again, enable it at launch with one of its launch flags or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](/docs/en/settings-reference#permissions-defaultmode) |
71| `bypassPermissions` | Terminal | The permission mode a new session would start in. To [bypass permissions](https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) again, enable it at launch with one of its launch flags or `permissions.defaultMode: "bypassPermissions"` in [user, `--settings`, or managed settings](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode) |
7272| `plan` | Terminal | Plan mode. With `--fork-session`, the permission mode a new session would start in |
7373| `plan` | Terminal, when a deny rule removes `ExitPlanMode` | The permission mode a new session would start in |
74| `auto` | Terminal | `auto`, only when your account still meets the [auto mode requirements](/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) |
75| Manual | Terminal | Manual when a new session would start in auto mode from the [built-in default](/docs/en/permission-modes.md#which-mode-a-session-starts-in). When a `defaultMode` from a settings file [takes effect](/docs/en/permission-modes.md#which-mode-a-session-starts-in), Claude Code starts the resumed session in that mode instead |
74| `auto` | Terminal | `auto`, only when your account still meets the [auto mode requirements](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) |
75| Manual | Terminal | Manual when a new session would start in auto mode from the [built-in default](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in). When a `defaultMode` from a settings file [takes effect](https://code.claude.com/docs/en/permission-modes.md#which-mode-a-session-starts-in), Claude Code starts the resumed session in that mode instead |
7676| `plan` | Non-interactive, under the [conditions below](#resume-in-plan-mode-with-p) | Plan mode |
7777| Any mode | Non-interactive, in any other case | The permission mode a new `claude -p` run would start in |
78| `plan` | VS Code | Plan mode, with [the exceptions on the VS Code page](/docs/en/vs-code.md#resume-past-conversations) |
78| `plan` | VS Code | Plan mode, with [the exceptions on the VS Code page](https://code.claude.com/docs/en/vs-code.md#resume-past-conversations) |
7979
8080##### Resume in plan mode with `-p`
8181
8282A `claude -p --resume` or `claude -p --continue` run resumes in plan mode only when all of these conditions hold:
8383
84* You pass [`--permission-prompt-tool`](/docs/en/cli-reference#cli-flags) and don't pass [`--permission-prompts none`](/docs/en/headless#turn-off-permission-prompts-in-unattended-runs), so that Claude Code can present the plan for approval
84* You pass [`--permission-prompt-tool`](https://code.claude.com/docs/en/cli-reference#cli-flags) and don't pass [`--permission-prompts none`](https://code.claude.com/docs/en/headless#turn-off-permission-prompts-in-unattended-runs), so that Claude Code can present the plan for approval
8585* You don't pass `--permission-mode` or `--dangerously-skip-permissions`
8686* You don't pass `--fork-session`
87* The run isn't started through [channels](/docs/en/channels.md)
88* No [deny rule](/docs/en/permissions.md#manage-permissions) removes the `ExitPlanMode` tool
87* The run isn't started through [channels](https://code.claude.com/docs/en/channels.md)
88* No [deny rule](https://code.claude.com/docs/en/permissions.md#manage-permissions) removes the `ExitPlanMode` tool
8989
9090### The "Resume this conversation?" dialog
9191
9292If you see the "Resume this conversation?" dialog when resuming a session, its estimate is the share of your 5-hour usage limit that the saved conversation alone would use. The estimate doesn't count what you've already used.
9393
94On Pro and Max plans, the dialog can appear when you resume a long conversation [after a long break](/docs/en/prompt-caching.md#resuming-a-session) or on a different model. The estimated use comes when you send your first message after **Resume**, not when you select it. Choose by whether your next task still needs the saved conversation:
94On Pro and Max plans, the dialog can appear when you resume a long conversation [after a long break](https://code.claude.com/docs/en/prompt-caching.md#resuming-a-session) or on a different model. The estimated use comes when you send your first message after **Resume**, not when you select it. Choose by whether your next task still needs the saved conversation:
9595
9696* **Resume**: keep working in the saved conversation.
9797* **Start a new conversation**: switch to work that doesn't need the saved conversation. To reopen it later, run [`/resume`](#use-the-session-picker) at the prompt. The estimate doesn't apply to your first message in the new conversation. If the option says that Claude can look up this conversation, you can still refer to earlier work in the new conversation.
from line 100
100100
101101Claude Code stores sessions per project directory. By default the session picker shows:
102102
103* Sessions from the current worktree, including [background sessions](/docs/en/agent-view.md), which are marked `bg` in the list
103* Sessions from the current worktree, including [background sessions](https://code.claude.com/docs/en/agent-view.md), which are marked `bg` in the list
104104* Sessions started elsewhere that added the current directory with `/add-dir`
105105
106106Use `Ctrl+W` to widen to all worktrees of the repository or `Ctrl+A` to widen to every project on this machine.
from line 107
107107
108108#### `/loop`, `-p`, Agent SDK, and background sessions
109109
110Sessions whose first prompt was a [`/loop`](/docs/en/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) command don't appear in the picker, and `claude --continue` skips them too. Running `/loop` later in a conversation doesn't hide the session.
110Sessions whose first prompt was a [`/loop`](https://code.claude.com/docs/en/scheduled-tasks#run-a-prompt-repeatedly-with-%2Floop) command don't appear in the picker, and `claude --continue` skips them too. Running `/loop` later in a conversation doesn't hide the session.
111111
112Claude Code leaves sessions created with [`claude -p`](/docs/en/headless) or the [Agent SDK](/docs/en/agent-sdk/overview.md) out of the session picker and out of `claude --continue`. You can still resume one by passing its session ID to `claude --resume <session-id>`. When you run [`claude -p --continue`](/docs/en/headless#continue-conversations), Claude Code includes `-p`, SDK, and `/loop` sessions.
112Claude Code leaves sessions created with [`claude -p`](https://code.claude.com/docs/en/headless) or the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) out of the session picker and out of `claude --continue`. You can still resume one by passing its session ID to `claude --resume <session-id>`. When you run [`claude -p --continue`](https://code.claude.com/docs/en/headless#continue-conversations), Claude Code includes `-p`, SDK, and `/loop` sessions.
113113
114`claude --continue` opens a [background session](/docs/en/agent-view.md) that has finished, but not one that is still running; opening finished background sessions requires Claude Code v2.1.257 or later. If your most recent conversation is one you [moved to the background](/docs/en/agent-view.md#send-the-session-to-the-background) and it is still running there, Claude Code exits with `Your most recent conversation is running in the background` and that session's ID. Attach to the session from [`claude agents`](/docs/en/agent-view#attach-to-a-session), or run `claude --resume` to pick another one.
114`claude --continue` opens a [background session](https://code.claude.com/docs/en/agent-view.md) that has finished, but not one that is still running; opening finished background sessions requires Claude Code v2.1.257 or later. If your most recent conversation is one you [moved to the background](https://code.claude.com/docs/en/agent-view.md#send-the-session-to-the-background) and it is still running there, Claude Code exits with `Your most recent conversation is running in the background` and that session's ID. Attach to the session from [`claude agents`](https://code.claude.com/docs/en/agent-view#attach-to-a-session), or run `claude --resume` to pick another one.
115115
116116#### Sessions in other worktrees and projects
117117
118When you select a session from another worktree of the same repository, Claude Code resumes it in place; when the session's own worktree no longer exists, Claude Code [resumes it in your current directory](/docs/en/worktrees.md#resume-a-worktree-session). When you select a session from an unrelated project, Claude Code copies a `cd` and resume command to your clipboard instead. If that project's directory no longer exists, Claude Code resumes the session in your current directory rather than copying a `cd` command that would fail.
118When you select a session from another worktree of the same repository, Claude Code resumes it in place; when the session's own worktree no longer exists, Claude Code [resumes it in your current directory](https://code.claude.com/docs/en/worktrees.md#resume-a-worktree-session). When you select a session from an unrelated project, Claude Code copies a `cd` and resume command to your clipboard instead. If that project's directory no longer exists, Claude Code resumes the session in your current directory rather than copying a `cd` command that would fail.
119119
120Moving a session with [`/cd`](/docs/en/commands) relocates it to the new directory's project storage, so it appears in that directory's picker afterward.
120Moving a session with [`/cd`](https://code.claude.com/docs/en/commands) relocates it to the new directory's project storage, so it appears in that directory's picker afterward.
121121
122122#### Resume by session ID or name
123123
124You can run `claude --resume <session-id>` from any directory, so you can resume a session that started elsewhere or moved with [`/cd`](/docs/en/commands). Claude Code looks for the ID in this order:
124You can run `claude --resume <session-id>` from any directory, so you can resume a session that started elsewhere or moved with [`/cd`](https://code.claude.com/docs/en/commands). Claude Code looks for the ID in this order:
125125
1261261. The current project directory and its git worktrees
1271272. Every other project on this machine
from line 144
144144| At startup | `claude -n auth-refactor` |
145145| During a session | `/rename auth-refactor`. The name also appears on the prompt bar |
146146| From the session picker | Highlight a session and press `Ctrl+R` |
147| On plan accept | Accepting a plan in [plan mode](/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) gives the session a generated title based on the plan unless you've already named it |
148| From claude.ai or the Claude app | Rename a [Remote Control session](/docs/en/remote-control.md#connect-from-another-device); Claude Code applies the same name in the CLI. Requires Claude Code v2.1.221 or later |
149| From the desktop app | Rename a session in the [desktop app](/docs/en/desktop.md#organize-and-find-sessions) |
147| On plan accept | Accepting a plan in [plan mode](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) gives the session a generated title based on the plan unless you've already named it |
148| From claude.ai or the Claude app | Rename a [Remote Control session](https://code.claude.com/docs/en/remote-control.md#connect-from-another-device); Claude Code applies the same name in the CLI. Requires Claude Code v2.1.221 or later |
149| From the desktop app | Rename a session in the [desktop app](https://code.claude.com/docs/en/desktop.md#organize-and-find-sessions) |
150150
151Once you name a session through a CLI route or from claude.ai, return to it with `claude --resume <name>` or `/resume <name>`; a desktop-app session resumes in the [desktop app](/docs/en/desktop.md#work-in-parallel-with-sessions). See [Resume a session](#resume-a-session) for how name resolution behaves across worktrees.
151Once you name a session through a CLI route or from claude.ai, return to it with `claude --resume <name>` or `/resume <name>`; a desktop-app session resumes in the [desktop app](https://code.claude.com/docs/en/desktop.md#work-in-parallel-with-sessions). See [Resume a session](#resume-a-session) for how name resolution behaves across worktrees.
152152
153153Sessions you don't name still get two labels that Claude Code assigns. Only the generated title works as a resume handle:
154154
155* Default display name: interactive sessions you never name still get a default display name when they start. The default combines the working directory's name with a two-character suffix, for example `my-app-3f`, and identifies the session in listings of running sessions, such as [agent view](/docs/en/agent-view.md) and `claude agents --json` output. The default isn't a resume handle. If you pass it to `claude --resume` or `/resume`, Claude Code doesn't find the session.
155* Default display name: interactive sessions you never name still get a default display name when they start. The default combines the working directory's name with a two-character suffix, for example `my-app-3f`, and identifies the session in listings of running sessions, such as [agent view](https://code.claude.com/docs/en/agent-view.md) and `claude agents --json` output. The default isn't a resume handle. If you pass it to `claude --resume` or `/resume`, Claude Code doesn't find the session.
156156* Generated title: if you don't name a session, Claude Code generates a session title for it. The title is a short summary of your first prompt, written by a background request to the small/fast model, normally a Haiku-class model. A `claude -p` run you start directly from a shell or script doesn't get one.
157157
158158 Accepting a plan replaces the generated title with a title based on the plan. You can pass either title to `claude --resume` or `/resume`, and Claude Code resolves it the same way as a name you set.
from line 179
179179
180180Sessions created with `/branch` or `--fork-session` get their own session IDs and appear as separate rows. When the picker finds more than one entry for the same session, it groups them under a single row. Press `→` to expand a group.
181181
182If Claude Code can't load the session you select from the `claude --resume` picker, it prints [`Failed to resume the conversation`](/docs/en/errors#failed-to-resume-the-conversation) with a command to retry, then exits with code 1. From the `/resume` picker inside a session, Claude Code reports the failure and your current conversation keeps running.
182If Claude Code can't load the session you select from the `claude --resume` picker, it prints [`Failed to resume the conversation`](https://code.claude.com/docs/en/errors#failed-to-resume-the-conversation) with a command to retry, then exits with code 1. From the `/resume` picker inside a session, Claude Code reports the failure and your current conversation keeps running.
183183
184184## Branch a session
185185
from line 207
207207| :- | :- |
208208| Conversation history | Copied into the branch up to the point you ran `/branch` |
209209| "Allow for this session" permission grants | Carried over; the branch runs in the same process, so your existing grants still apply. If you fork into a separate process with `--fork-session`, the new process starts without them and you re-approve there |
210| In-flight [background subagents](/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) and [background Bash commands](/docs/en/interactive-mode.md#background-bash-commands) | Keep running. Their output appears in the new branch you switched into, not in the original session |
211| [Remote Control](/docs/en/remote-control.md) connection | Stays connected. A phone or browser connected to the session follows you into the branch and keeps receiving new messages there |
210| In-flight [background subagents](https://code.claude.com/docs/en/sub-agents.md#run-subagents-in-foreground-or-background) and [background Bash commands](https://code.claude.com/docs/en/interactive-mode.md#background-bash-commands) | Keep running. Their output appears in the new branch you switched into, not in the original session |
211| [Remote Control](https://code.claude.com/docs/en/remote-control.md) connection | Stays connected. A phone or browser connected to the session follows you into the branch and keeps receiving new messages there |
212212
213If you resume the same session in two terminals without forking, messages from both interleave into one transcript. For checkpoint-based rewind within a single session, see [Checkpointing](/docs/en/checkpointing.md).
213If you resume the same session in two terminals without forking, messages from both interleave into one transcript. For checkpoint-based rewind within a single session, see [Checkpointing](https://code.claude.com/docs/en/checkpointing.md).
214214
215215## Manage context within a session
216216
217217These commands control what's in the context window without leaving the session:
218218
219* **`/clear`**: start fresh with an empty context. Claude Code saves the previous session; resume it with `/resume`, or, in the same Claude Code process, from [the rewind menu's previous-session entry](/docs/en/checkpointing.md#rewind-past-a-cleared-conversation). With no argument, the new session keeps a name you set with `--name` or `/rename`, but not an AI-generated session title. To name the session you're leaving instead, pass the name, as in `/clear release-prep`; the new session then starts unnamed
219* **`/clear`**: start fresh with an empty context. Claude Code saves the previous session; resume it with `/resume`, or, in the same Claude Code process, from [the rewind menu's previous-session entry](https://code.claude.com/docs/en/checkpointing.md#rewind-past-a-cleared-conversation). With no argument, the new session keeps a name you set with `--name` or `/rename`, but not an AI-generated session title. To name the session you're leaving instead, pass the name, as in `/clear release-prep`; the new session then starts unnamed
220220* **`/compact [instructions]`**: replace history with a summary, optionally focused on what you specify
221221* **`/context`**: show what is currently consuming context
222222
223For how compaction interacts with CLAUDE.md, skills, and rules, see the [context window guide](/docs/en/context-window.md). For strategies on when to clear versus compact, see [Best practices](/docs/en/best-practices.md#manage-your-session).
223For how compaction interacts with CLAUDE.md, skills, and rules, see the [context window guide](https://code.claude.com/docs/en/context-window.md). For strategies on when to clear versus compact, see [Best practices](https://code.claude.com/docs/en/best-practices.md#manage-your-session).
224224
225225## Export and locate session data
226226
from line 230
230230
231231`/export` produces a rendered transcript for a person to read. The interfaces below produce structured data for a script to parse: a JSON result from a run, the path to a session's transcript file, or a live stream of events. Pick by what triggers the script:
232232
233* **Run Claude once and capture the result**: invoke `claude -p` with [`--output-format json` or `stream-json`](/docs/en/headless#get-structured-output) to capture the result, session ID, usage, and cost of a non-interactive run as structured JSON.
234* **Ask an existing session a question**: pass a session ID to [`claude -p --resume`](/docs/en/headless#continue-conversations) to send a follow-up prompt, such as a summary request, and capture the structured response.
235* **React to session events**: read the `transcript_path` field that [hooks](/docs/en/hooks.md#common-input-fields) and [status line commands](/docs/en/statusline.md#available-data) receive as input. A `SessionEnd` hook can archive the transcript when a session ends.
236* **Embed Claude in a TypeScript or Python app**: use the [Agent SDK](/docs/en/agent-sdk/overview.md) to receive each message programmatically.
233* **Run Claude once and capture the result**: invoke `claude -p` with [`--output-format json` or `stream-json`](https://code.claude.com/docs/en/headless#get-structured-output) to capture the result, session ID, usage, and cost of a non-interactive run as structured JSON.
234* **Ask an existing session a question**: pass a session ID to [`claude -p --resume`](https://code.claude.com/docs/en/headless#continue-conversations) to send a follow-up prompt, such as a summary request, and capture the structured response.
235* **React to session events**: read the `transcript_path` field that [hooks](https://code.claude.com/docs/en/hooks.md#common-input-fields) and [status line commands](https://code.claude.com/docs/en/statusline.md#available-data) receive as input. A `SessionEnd` hook can archive the transcript when a session ends.
236* **Embed Claude in a TypeScript or Python app**: use the [Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview.md) to receive each message programmatically.
237237
238238The example below uses the second interface. It sends a follow-up prompt to an existing session and reads the answer with `jq`:
239239
from line 251
251251
252252| To | Set | Where |
253253| - | - | - |
254| Move storage off `~/.claude` | [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) | Environment variable |
255| [Name the `<project>` directory yourself](#name-the-project-directory-yourself) | [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/en/env-vars) | Environment variable |
256| Change the 30-day retention | [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) | `settings.json` |
257| Set an age limit for [Claude Desktop and Cowork transcripts](/docs/en/claude-directory.md#cleaned-up-automatically) | [`desktopSessionCleanupPeriodDays`](/docs/en/settings-reference#desktopsessioncleanupperioddays) | User settings, managed settings, or `--settings` |
258| Limit how large a `-p` or Agent SDK session's transcript file grows | [`CLAUDE_CODE_TRANSCRIPT_LOCAL_GC`](/docs/en/env-vars) | Environment variable |
259| Suppress transcript writes in all modes | [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/en/env-vars) | Environment variable |
260| Suppress writes for one non-interactive run | [`--no-session-persistence`](/docs/en/cli-reference) | CLI flag with `claude -p` |
254| Move storage off `~/.claude` | [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars) | Environment variable |
255| [Name the `<project>` directory yourself](#name-the-project-directory-yourself) | [`CLAUDE_CODE_PROJECT_DIR_NAME`](https://code.claude.com/docs/en/env-vars) | Environment variable |
256| Change the 30-day retention | [`cleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#cleanupperioddays) | `settings.json` |
257| Set an age limit for [Claude Desktop and Cowork transcripts](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically) | [`desktopSessionCleanupPeriodDays`](https://code.claude.com/docs/en/settings-reference#desktopsessioncleanupperioddays) | User settings, managed settings, or `--settings` |
258| Limit how large a `-p` or Agent SDK session's transcript file grows | [`CLAUDE_CODE_TRANSCRIPT_LOCAL_GC`](https://code.claude.com/docs/en/env-vars) | Environment variable |
259| Suppress transcript writes in all modes | [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](https://code.claude.com/docs/en/env-vars) | Environment variable |
260| Suppress writes for one non-interactive run | [`--no-session-persistence`](https://code.claude.com/docs/en/cli-reference) | CLI flag with `claude -p` |
261261
262262### Delete session data
263263
264Transcripts age out under the [retention sweep rules](/docs/en/claude-directory.md#cleaned-up-automatically). To delete a project's transcripts and related state sooner, run [`claude purge`](/docs/en/claude-directory#clear-local-data). If you delete a [background session](/docs/en/agent-view.md) with [`claude rm <id>`](/docs/en/agent-view#what-deleting-a-session-removes), its transcript stays on disk and remains available through `claude --resume`.
264Transcripts age out under the [retention sweep rules](https://code.claude.com/docs/en/claude-directory.md#cleaned-up-automatically). To delete a project's transcripts and related state sooner, run [`claude purge`](https://code.claude.com/docs/en/claude-directory#clear-local-data). If you delete a [background session](https://code.claude.com/docs/en/agent-view.md) with [`claude rm <id>`](https://code.claude.com/docs/en/agent-view#what-deleting-a-session-removes), its transcript stays on disk and remains available through `claude --resume`.
265265
266266### Name the project directory yourself
267267
268By default, Claude Code derives the `<project>` name from the whole working directory path. To choose the name yourself, set `CLAUDE_CODE_PROJECT_DIR_NAME` alongside `CLAUDE_CONFIG_DIR`. Claude Code then stores that session's transcripts and [auto memory](/docs/en/memory.md#auto-memory) under your name. This suits a host that embeds Claude Code and gives each session its own config directory. Requires Claude Code v2.1.234 or later.
268By default, Claude Code derives the `<project>` name from the whole working directory path. To choose the name yourself, set `CLAUDE_CODE_PROJECT_DIR_NAME` alongside `CLAUDE_CONFIG_DIR`. Claude Code then stores that session's transcripts and [auto memory](https://code.claude.com/docs/en/memory.md#auto-memory) under your name. This suits a host that embeds Claude Code and gives each session its own config directory. Requires Claude Code v2.1.234 or later.
269269
270270For example, this launch keeps tenant A's data under `/srv/tenant-a` and names its project directory `work`:
271271
from line 287
287287
288288These pages cover related session and parallelism mechanics:
289289
290* [Worktrees](/docs/en/worktrees.md): run isolated parallel sessions on separate branches
291* [Checkpointing](/docs/en/checkpointing.md): rewind code and conversation to an earlier point
292* [Context window](/docs/en/context-window.md): what fills context and what survives compaction
293* [Non-interactive mode](/docs/en/headless.md): session behavior under `claude -p`
290* [Worktrees](https://code.claude.com/docs/en/worktrees.md): run isolated parallel sessions on separate branches
291* [Checkpointing](https://code.claude.com/docs/en/checkpointing.md): rewind code and conversation to an earlier point
292* [Context window](https://code.claude.com/docs/en/context-window.md): what fills context and what survives compaction
293* [Non-interactive mode](https://code.claude.com/docs/en/headless.md): session behavior under `claude -p`
294294
No line in this hunk matches that.