Session Management

What You’ll Learn

A Claude Code session is a saved conversation associated with a project directory. The stable way to work with it is through documented commands, flags, session IDs, exports, and SDK messages—not by reverse-engineering transcript records.

This session covers the public contract for continuing, finding, branching, and automating conversations.

Resume the Right Conversation

Interface	Behavior
claude --continue or claude -c	Resume the most recent conversation in the current directory
claude --resume	Open the interactive session picker
claude --resume <name-or-id>	Resume a specific named session or session ID
/resume	Switch conversations from inside Claude Code

claude --continue
claude --resume auth-refactor
claude --resume 550e8400-e29b-41d4-a716-446655440000

Session lookup is project-aware. ID lookup is scoped to the current project directory and its Git worktrees, so launch the command from the project where the session began.

Name Sessions Before You Need Them

Use a descriptive name when starting:

claude --name auth-refactor
# short form
claude -n auth-refactor

Or rename the current session:

/rename auth-refactor

Names are better human handles than copying UUIDs into runbooks. Use one workstream per session, such as auth-refactor, release-audit, or incident-142.

What Resume Restores

The documented restore behavior includes:

• conversation history, including tool calls and results;
• the prior model when it is still available and not overridden;
• the prior permission mode, with important exceptions;
• an active goal and unexpired scheduled tasks where supported.

plan and bypassPermissions are not restored automatically. Standard settings files are read again at launch. Launch-only inputs such as extra settings, plugin directories, MCP config, fallback models, and added directories may need to be passed again.

Resume restores conversation state; it does not reverse or recreate reality. Files may have changed, processes may have stopped, credentials may have expired, and remote systems may have moved on. Start a resumed task by checking the current repository and external state.

Branch Instead of Overwriting a Path

Branching copies the conversation so far into a new session and leaves the original intact:

/branch try-streaming-approach

From the CLI:

claude --continue --fork-session
claude --resume auth-refactor --fork-session

The branch receives a new session ID. Session-scoped permission approvals do not carry over. Avoid resuming the same non-forked session in two terminals because both can append messages to one conversation.

Use branching to compare approaches; use a Git branch or worktree to isolate file changes. They solve different problems.

Manage Context Inside a Session

/context
/compact focus on decisions, changed files, and remaining risks
/clear

• /context shows what consumes the current context window.
• /compact replaces older context with a summary.
• /clear starts a new empty conversation while preserving the previous one for /resume.

Compaction is lossy summarization, not durable project memory. Put lasting instructions in CLAUDE.md and decisions in repository artifacts.

Export or Automate Through Supported Interfaces

For a person-readable record, use /export and optionally provide a filename. For software, choose a structured public interface:

claude -p --output-format json "Summarize this repository"
claude -p --output-format stream-json --verbose "Run the verification"
claude -p --resume <session-id> --output-format json "Summarize what changed"

Other supported choices are Agent SDK messages and the transcript_path supplied to hooks. The default transcript may be stored locally as JSONL, but its entry format is explicitly internal and can change between releases. Do not build a parser around undocumented relationships or record types.

For a one-off non-interactive run that should not write a session transcript, use the documented --no-session-persistence flag with -p.

A Durable Handoff Pattern

Before leaving a long-running task:

1. name the session;
2. write decisions and unresolved risks into the repository;
3. record the current branch, worktree, test result, and external status;
4. commit or safely preserve file changes;
5. on resume, verify those facts before continuing.

The session preserves conversational continuity. The repository and live systems remain the source of truth.

Official Sources

• Manage sessions
• Claude Code CLI reference

Next Session

Next, design CLAUDE.md as durable project context that remains useful across many separate sessions.