Claude Code Sessions: Easy Continuity Guide

Sessions are the backbone of working with Claude Code across time and devices. A session is a saved conversation tied to your project directory, stored locally as you work. You can resume it after exiting, branch it to try a different approach, continue it from your phone, or rewind file changes when something goes wrong.

Sessions: What You’ll Learn

This guide covers how sessions work across the CLI, the desktop app, and the web so you never lose momentum when life interrupts your work. You will learn to resume, branch, teleport, and rewind sessions with confidence using verified commands and flags.

Before diving in, a quick note on scope. This post focuses on continuing and managing sessions across devices and rewinding changes within a session. It is distinct from our guide on Memory and Context Persistence, which covers CLAUDE.md files and context window management. It also differs from Headless Mode and CI Automation, which deals with non-interactive one-shot invocation. We link to both throughout where those topics intersect.

What Is a Claude Code Session?

A session is a saved conversation tied to a project directory. As you interact with Claude Code, it continuously writes your conversation to a local transcript file. This means you can exit the tool, restart your machine, or run /clear, and the previous conversation remains saved and resumable.

Sessions are scoped per project directory. The session picker shows interactive sessions from your current worktree by default, plus any sessions started elsewhere that added your current directory with /add-dir. You can widen the view to all worktrees of your repository or to every project on your machine.

The desktop app, Claude Code on the web, and the VS Code extension each maintain their own session history. This page focuses on the CLI, but the concepts transfer across surfaces. For a broader overview of what Claude Code can do, see our Advanced Features Guide.

Transcripts are stored as JSONL files at ~/.claude/projects/<project>/<session-id>.jsonl, where the project path has non-alphanumeric characters replaced with hyphens. Each line is a JSON object for a message, tool use, or metadata entry. The internal format changes between versions, so prefer the /export command or script interfaces over parsing these files directly.

Configuring Session Storage

You can control where and how long transcripts are kept. The table below summarizes the key settings:

Goal	Setting	Where
Move storage off ~/.claude	CLAUDE_CONFIG_DIR	Environment variable
Change the 30-day retention	cleanupPeriodDays	settings.json
Suppress transcript writes	CLAUDE_CODE_SKIP_PROMPT_HISTORY	Environment variable
Suppress writes for one run	--no-session-persistence	CLI flag with claude -p

These settings give you control over disk usage and privacy. The default 30-day retention means old conversations are automatically cleaned up alongside their checkpoints, keeping your workspace tidy without manual intervention.

Resuming and Switching Sessions

The most common session operation is resuming where you left off. Claude Code offers several entry points, each suited to a different situation:

# Resume the most recent session in the current directory
claude --continue

# Open the interactive session picker
claude --resume

# Resume a named session directly
claude --resume auth-refactor

# Resume the session linked to a pull request
claude --from-pr 42

# Switch sessions from inside an active session
/resume

If you created a session with claude -p (headless mode) or the Agent SDK, it does not appear in the session picker. You can still resume it by passing its session ID to claude --resume <session-id>, run from the directory where the session was originally started. Session ID lookup is scoped to the current project directory and its git worktrees.

Naming Sessions for Easy Recall

Descriptive names make sessions findable in the picker and resumable by name. This matters most when you juggle several tasks in parallel. You can set a name at several points:

# Name a session at startup
claude -n auth-refactor

# Rename during a session (name appears on the prompt bar)
/rename auth-refactor

# Rename from the session picker: highlight a session and press Ctrl+R

Once named, return to it with claude --resume <name> or /resume <name>. Both forms look for an exact match and resume it directly, even if it lives in a different worktree. If the name is ambiguous, claude --resume <name> opens the picker with the name pre-filled as a search term, while /resume <name> reports an error.

Interactive sessions you never name still get a default display name starting from v2.1.196, combining the working directory name with a two-character suffix (for example, my-app-3f). This default is not a resume handle; only names you set explicitly are matched by --resume and /resume.

Using the Session Picker

Run /resume inside a session, or claude --resume with no arguments, to open the interactive session picker. The picker supports keyboard shortcuts for navigation, search, and widening the scope of visible sessions:

Shortcut	Action
Up / Down	Navigate between sessions
Right / Left	Expand or collapse grouped sessions
Enter	Resume the highlighted session
Space	Preview session content
Ctrl+R	Rename the highlighted session
Ctrl+A	Show sessions from all projects on this machine
Ctrl+W	Show sessions from all worktrees of the current repository
Ctrl+B	Filter to sessions from the current git branch
Esc	Exit the picker or search mode

Each row shows the session name if set, otherwise the conversation summary or first prompt, along with time since last activity, message count, and git branch. You can also paste a GitHub, GitLab, or Bitbucket pull request URL into search mode to find the session that created it.

Forked sessions created with /branch, /rewind, or --fork-session are grouped under their root session. Press Right to expand a group and see its branches.

Branching Sessions

Branching creates a copy of the conversation so far and switches you into it, leaving the original intact. Use it to try a different approach without losing the path you were on. From inside a session, run /branch with an optional name:

/branch try-streaming-approach

If you omit the name, Claude Code names the new branch after the first prompt in the conversation. From the command line, combine --continue or --resume with --fork-session:

claude --continue --fork-session

The original session remains available in the picker. The /branch confirmation prints two session IDs: the new branch you are now in and the original. To return to the original, pass its ID to /resume, use the picker, or run /resume <original-name>.

One important detail: permissions you approved with “allow for this session” do not carry over to the new branch. If you resume the same session in two terminals without forking, messages from both interleave into one transcript, which can cause confusion.

Managing Context Within a Session

Several commands control what occupies the context window without leaving the session:

• /clear: start fresh with an empty context. The previous conversation is saved and resumable.
• /compact [instructions]: replace history with a summary, optionally focused on what you specify.
• /context: show what is currently consuming context.

For strategies on when to clear versus compact, and how compaction interacts with CLAUDE.md and skills, see our guide on Memory and Context Persistence. That post covers context window management in depth, which complements the session continuity techniques covered here.

Remote Control: Continue From Any Device

Remote Control connects claude.ai/code or the Claude mobile app to a Claude Code session running on your machine. Start a task at your desk, then pick it up from your phone on the couch or a browser on another computer. Claude keeps running locally the entire time, so nothing moves to the cloud.

With Remote Control, your full local environment stays available remotely: your filesystem, MCP servers, tools, and project configuration all remain in place. Typing @ autocompletes file paths from your local project. The conversation stays in sync across all connected devices, so you can send messages from your terminal, browser, and phone interchangeably.

Starting a Remote Control Session

You can start Remote Control from the CLI in three ways, or from VS Code with the /remote-control command:

# Server mode: stays running, waits for remote connections
claude remote-control

# Interactive session with Remote Control enabled
claude --remote-control
# Shorthand:
claude --rc

# From inside an existing session
/remote-control
# Shorthand:
/rc

In server mode, the process stays running in your terminal, displaying a session URL and connection status. Press spacebar to show a QR code for quick access from your phone. You can pass a custom title with --name "My Project" and control how sessions are spawned with --spawn (options: same-dir, worktree, or session).

Server mode also supports --capacity <N> to set the maximum number of concurrent sessions (default 32), and --[no-]create-session-in-dir to pre-create a session when the server starts. From v2.1.200, you can resume a previous Remote Control session with -c or --session-id <id>.

Connecting From Another Device

Once a Remote Control session is active, connect from another device in any of these ways:

• Open the session URL in any browser to go directly to the session on claude.ai/code.
• Scan the QR code shown alongside the session URL to open it in the Claude app.
• Open claude.ai/code or the Claude mobile app and find the session by name in the session list.

In the Claude mobile app, tap Code in the navigation to reach the session list. Remote Control sessions show a computer icon with a green status dot when online. If you do not have the app yet, run /mobile inside Claude Code to display a download QR code for iOS or Android.

Requirements and Limitations

Remote Control requires Claude Code v2.1.51 or later and a claude.ai subscription (Pro, Max, Team, or Enterprise). API keys are not supported. On Team and Enterprise plans, an Owner must enable the Remote Control toggle in admin settings. It is not available on Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry.

As of v2.1.196, Remote Control is also disabled when ANTHROPIC_BASE_URL points at a host other than api.anthropic.com, such as an LLM gateway or proxy. The local process must keep running; if you close the terminal, the session ends. If your machine is awake but offline for more than roughly 10 minutes, the session times out.

To enable Remote Control automatically for every interactive session, run /config and set Enable Remote Control for all sessions to true. Mobile push notifications (v2.1.110+) can alert you when a long-running task finishes or when Claude needs a decision. Enable them in /config with Push when Claude decides or Push when actions required.

Remote Control vs Claude Code on the Web

Both features use the claude.ai/code interface, but the key difference is where the session runs. Remote Control executes on your machine, so your local MCP servers, tools, and project configuration stay available. Claude Code on the web executes in Anthropic-managed cloud infrastructure. Use Remote Control when you are mid-task locally and want to keep going from another device. Use the web when you want to start a task with no local setup.

Teleporting Sessions Between Web and Terminal

Claude Code on the web runs tasks on Anthropic-managed cloud infrastructure at claude.ai/code. Sessions persist even if you close your browser, and you can monitor them from the Claude mobile app. Two CLI flags let you move work between the web and your terminal.

To start a new cloud session from the command line, use the --cloud flag:

# Create a new cloud session for your current repository
claude --cloud "Fix the authentication bug in src/auth/login.ts"

This clones your current directory’s GitHub remote at your current branch, so push first if you have local commits. The task runs in the cloud while you continue working locally. The older --remote spelling still works as a deprecated alias for --cloud.

To pull an existing cloud session into your terminal, use --teleport:

# Pull a cloud session into your local terminal
claude --teleport

Session handoff from the CLI is one-way: you can pull cloud sessions into your terminal with --teleport, but you cannot push an existing terminal session to the web. The --cloud flag creates a new cloud session rather than moving an existing one. Use /tasks in the CLI to check progress on cloud sessions.

This distinction matters for workflow design. If you start a task locally and want to move it to the cloud, the Desktop app’s Continue in menu can send a local session to the web. But from the CLI alone, --teleport only pulls web sessions down, and --cloud only creates new ones.

The Desktop App and Session Continuity

The Claude Desktop app has a Code tab where each conversation is a session with its own chat history, project folder, and code changes, independent of any other session. The sidebar lists your sessions and lets you run several in parallel. For Git repositories, each session gets its own isolated copy of your project using Git worktrees, so changes in one session do not affect others until you commit them.

Parallel Sessions and Isolation

Click New session in the sidebar, or press Cmd+N on macOS or Ctrl+N on Windows, to work on multiple tasks in parallel. Press Ctrl+Tab and Ctrl+Shift+Tab to cycle through sessions. Worktrees are stored in <project-root>/.claude/worktrees/ by default, and you can customize this location in Settings.

The desktop app sends an OS notification when a Code session finishes a task and you are not currently viewing that session. You can also enable auto-archive so sessions archive themselves when their pull request merges or closes, keeping the sidebar clean.

Continue in Another Surface

The Continue in menu, accessible from the VS Code icon in the bottom right of the session toolbar, lets you move your session to another surface. You can send a local session to Claude Code on the Web, where Desktop pushes your branch, generates a summary, and creates a new cloud session with the full context. This requires a clean working tree and is not available for SSH sessions. You can then choose to archive the local session or keep it.

You can also open your project in a supported IDE at the current working directory. This is the desktop-native way to hand off a terminal session to the web, complementing the CLI’s --cloud and --teleport flags.

Dispatch: Tasks From Your Phone

Dispatch is a persistent conversation in the Cowork tab that lives on your phone. You message Dispatch a task, and it decides how to handle it. A task can end up as a Code session in two ways: you ask for one directly, or Dispatch decides the task is development work and spawns one. The Code session appears in the sidebar with a Dispatch badge, and you get a push notification when it finishes or needs your approval. Dispatch requires a Pro or Max plan.

Checkpointing: Rewind Within a Session

Checkpointing is Claude Code’s built-in safety net for undoing changes within a session. As you work, it automatically captures the state of your code before each edit. Every user prompt creates a new checkpoint, and checkpoints persist across sessions, so you can access them in resumed conversations. They are automatically cleaned up along with sessions after 30 days, configurable via cleanupPeriodDays in settings.json.

Opening the Rewind Menu

Run /rewind, or press Esc twice when the prompt input is empty, to open the rewind menu. If the prompt input contains text, double Esc clears it instead of opening the menu. The rewind menu lists each prompt you sent during the session. Select the point you want to act on, then choose an action:

• Restore code and conversation: revert both code and conversation to that point.
• Restore conversation: rewind to that message while keeping current code.
• Restore code: revert file changes while keeping the conversation.
• Summarize from here: compress the conversation from this point forward into a summary, freeing context space.
• Summarize up to here: compress the conversation before this point into a summary, keeping later messages intact.
• Never mind: return to the message list without making changes.

After restoring the conversation or choosing Summarize from here, the original prompt from the selected message is restored into the input field so you can re-send or edit it. The original messages are always preserved in the session transcript, so Claude can reference details if needed.

Summarize vs Restore

The restore options revert state: they undo code changes, conversation history, or both. The summarize options compress part of the conversation into an AI-generated summary without changing files on disk. Use Summarize from here to discard a side discussion while keeping early context in full detail. Use Summarize up to here to compress early setup discussion while keeping recent work in full detail. This is similar to /compact, but targeted to a specific point rather than the entire conversation.

If you ran /clear earlier in the same process, the rewind menu shows an additional entry labeled /resume <session-id> (previous session). Select it to resume the conversation that was active before /clear ran. This requires v2.1.191 or later.

Checkpointing Limitations

Checkpointing does not track files modified by bash commands. If Claude runs rm file.txt, mv old.txt new.txt, or cp source.txt dest.txt, those modifications cannot be undone through rewind. Only direct file edits made through Claude’s file editing tools are tracked.

Checkpointing also only tracks files edited within the current session. Manual changes you make outside of Claude Code and edits from other concurrent sessions are normally not captured. Checkpoints are designed for quick, session-level recovery and complement, but do not replace, proper version control. Think of checkpoints as local undo and Git as permanent history.

Exporting and Locating Session Data

Run /export to open a menu that lets you copy the current conversation to your clipboard or save it as a plain-text file, with messages and tool outputs rendered as readable text. Pass a filename to skip the menu and write directly to that file. This produces a rendered transcript for a person to read.

For scripts, several interfaces produce structured data. Invoke claude -p with --output-format json to capture the result, session ID, usage, and cost of a non-interactive run. Pass a session ID to claude -p --resume to send a follow-up prompt and capture the structured response. Read the transcript_path field that hooks and status line commands receive to react to session events. For embedding in apps, use the Agent SDK.

The example below sends a follow-up prompt to an existing session and reads the answer with jq:

claude -p --resume <session-id> --output-format json "summarize what we changed" | jq -r '.result'

For more on non-interactive invocation patterns, see our guide on Headless Mode and CI Automation. That post covers claude -p, output formats, and scripting in depth.

A Worked Example

Imagine you are refactoring an authentication module on your laptop. You start a named session, work through the morning, then need to step away. Here is how sessions, Remote Control, and checkpointing work together in a realistic flow.

First, you start the session with a descriptive name so it is easy to find later:

claude -n auth-refactor

You work for an hour, asking Claude to extract a token-refresh utility and update the login handler. Halfway through, you realize the approach is getting tangled. Rather than starting over, you branch the session to try a cleaner strategy:

/branch cleaner-token-approach

The original session stays intact in the picker. You continue in the branch, and this time the refactor goes smoothly. But then Claude makes a change that breaks a test. You open the rewind menu with /rewind, select the prompt before the breaking change, and choose Restore code. This reverts the file changes while keeping the conversation, so you can guide Claude toward a fix without losing the discussion.

Now it is lunchtime. You enable Remote Control so you can review progress from your phone:

/remote-control auth-refactor

A session URL appears in your terminal. You scan the QR code with the Claude app, and the conversation opens on your phone. While you are away, you send a message asking Claude to write a summary of the remaining work. Claude responds, and you approve a file edit from your phone. When you return to your laptop, the conversation is already in sync.

In the afternoon, you need to run a long test suite that will take 20 minutes. Instead of tying up your terminal, you send it to the cloud:

claude --cloud "Run the full test suite and fix any failures in the auth module"

The cloud session clones your repository and starts working. You check progress with /tasks or open claude.ai/code on your phone. When the tests pass, you pull the session back into your terminal with --teleport to review the final diff locally before committing.

Throughout this flow, the session persisted across devices, surfaces, and interruptions. The original branch, the Remote Control connection, and the cloud task all traced back to the same project directory, and checkpointing gave you a safety net at every step. For official documentation on all these features, see the Claude Code sessions reference.

Sessions: Common Mistakes to Avoid

Even with good tools, a few habits can undermine your session workflow. Watch out for these pitfalls:

• Never naming your sessions. Unnamed sessions are hard to find in the picker when you have several running. Use claude -n <name> at startup or /rename mid-session so you can resume by name.
• Resuming the same session in two terminals without forking. Messages from both terminals interleave into one transcript, creating confusion. Use /branch or --fork-session if you need parallel copies.
• Expecting checkpointing to undo bash command changes. Files modified by bash commands like rm, mv, or cp are not tracked. Use version control for operations that bypass Claude’s file editing tools.
• Closing the terminal during Remote Control. Remote Control runs as a local process. If you close the terminal, quit VS Code, or stop the claude process, the remote session ends. Keep the process running or use server mode.

Sessions: Best Practices

• Name sessions at startup. A descriptive name like auth-refactor or fix-login-bug makes the session instantly findable in the picker and resumable by name with claude --resume <name>.
• Branch before experimenting. When you want to try a risky or different approach, run /branch first. The original session stays intact, and you can return to it if the experiment fails.
• Use Remote Control for context switches, not for starting new work. Remote Control continues a local session from another device. For new tasks with no local setup, use Claude Code on the web with --cloud instead.
• Enable auto-connect if you work across devices often. Set Enable Remote Control for all sessions to true in /config so every interactive session is automatically available remotely without an extra command.
• Treat checkpoints as undo, Git as history. Use /rewind for quick session-level recovery, but commit your work to Git for permanent version history. Checkpoints complement version control; they do not replace it.

Sessions: Frequently Asked Questions

How do I resume my most recent Claude Code session?

Run claude --continue to resume the most recent session in your current directory. Use claude --resume to open the picker, or claude --resume <name> to resume a named session directly.

What is the difference between Remote Control and Claude Code on the web?

Remote Control runs on your machine, keeping your local environment available. Claude Code on the web runs on Anthropic cloud infrastructure. Use Remote Control to continue local work remotely; use the web for new tasks without setup.

Can checkpointing undo changes made by bash commands?

No. Checkpointing only tracks files edited through Claude’s file editing tools. Changes made by bash commands like rm, mv, or cp cannot be undone through rewind. Use Git for those operations.

How do I move a cloud session to my local terminal?

Run claude --teleport to pull a cloud session into your terminal. Handoff is one-way from the CLI: you can pull web sessions down but cannot push a terminal session to the web without the Desktop app.

Where are Claude Code session transcripts stored?

Transcripts are stored as JSONL files at ~/.claude/projects/<project>/<session-id>.jsonl. You can move this location with the CLAUDE_CONFIG_DIR environment variable and change the 30-day retention with cleanupPeriodDays in settings.json.

If you want to dig deeper into how Claude Code remembers context across sessions, check out our companion guide on Memory and Context Persistence.

Sessions are the connective tissue of a productive Claude Code workflow: they let you pause, resume, branch, and continue your work across devices and surfaces. Master the picker, naming, Remote Control, teleport, and rewind, and you will rarely lose momentum to an interruption again.