Session Management handles the lifecycle of conversations with Claude Code, including creating, persisting, resuming, forking, and organizing sessions. This system enables users to maintain context across multiple interactions, work on different conversation threads, and seamlessly continue previous work.
For information about context management within a session, see Context Window & Compaction. For CLI commands used to interact with sessions, see CLI Commands & Interaction Modes.
Sessions in Claude Code represent persistent conversation threads that maintain full context including messages, tool executions, and state. Each session exists independently with its own history, working directory, and configuration.
Figure 1: Session State Transitions
Sources: CHANGELOG.md1-641
Every session receives a unique identifier automatically. Session IDs are used internally for persistence and can be specified explicitly when forking sessions.
| Property | Description | Example |
|---|---|---|
| Auto-generated ID | UUID assigned at session creation | a3b4c5d6-e7f8-9012-3456-789abcdef012 |
| Custom ID | User-specified via --session-id | feature-auth-refactor |
| Named sessions | Human-readable aliases via /rename | "Fix login bug" |
Sessions can be assigned human-readable names for easier identification and resumption.
Figure 2: Session Naming Flow
Key Commands:
/rename - Assign a custom name to current session/tag - Add tags for categorizationclaude --resume <name> - Resume by name from CLI/resume <name> - Resume by name from REPLSources: CHANGELOG.md608 CHANGELOG.md200
Sessions are persisted to disk with transcript files and metadata:
Figure 3: Session Storage Architecture
Sessions persist automatically throughout their lifecycle:
| Event | Persistence Action |
|---|---|
| Message sent | Transcript updated with user message |
| Tool execution | Tool use and result saved to transcript |
| Hook execution | Hook context saved as saved_hook_context |
| Session exit | Full state committed to disk |
| Session resume | Transcript loaded from disk |
Session resume has been optimized to reduce memory usage:
parentUuid cycle detectionSources: CHANGELOG.md106 CHANGELOG.md101 CHANGELOG.md114
Figure 4: Session Resume Pathways
The /resume command presents an interactive picker:
Features:
Preview Content:
Sources: CHANGELOG.md8 CHANGELOG.md54 CHANGELOG.md226 CHANGELOG.md613
When resuming, sessions maintain:
--agent flag specification (reused by default since 2.1.32)--system-prompt)Sources: CHANGELOG.md69 CHANGELOG.md612
Session resumption includes robust error handling:
| Error Type | Recovery Mechanism | Version |
|---|---|---|
| Orphaned tool results | Skip invalid tool_result blocks | 2.1.30 |
| Corrupted transcripts | Detect parentUuid cycles and halt | 2.1.30 |
| Transient server errors | Recover from 409 conflicts | 2.1.0 |
| API errors during tool execution | Skip problematic tool results | 2.1.21 |
| Saved hook context | Optimize startup performance | 2.1.29 |
Sources: CHANGELOG.md425 CHANGELOG.md101 CHANGELOG.md424 CHANGELOG.md154 CHANGELOG.md114
Session forking creates a new independent session branching from a specific point in conversation history.
Figure 5: Session Forking Model
CLI Usage:
claude --resume --fork-session [--session-id custom-id]
Skill Frontmatter:
Sources: CHANGELOG.md185 CHANGELOG.md613 CHANGELOG.md384 CHANGELOG.md522
OAuth-authenticated users can access sessions stored remotely on claude.ai.
Figure 6: Remote Session Architecture
Capabilities:
/teleport command for claude.ai subscribers (2.1.0)/remote-env command for remote configuration (2.1.0)VS Code Integration:
Sources: CHANGELOG.md57-59 CHANGELOG.md406-407 CHANGELOG.md126
Sessions automatically track the Git branch from which they were started:
Sessions can be linked to GitHub pull requests:
Figure 7: Pull Request Linking
PR Linking Features:
--from-pr flag to resume sessions by PR number or URL (2.1.27)gh pr create (2.1.27)Sessions created from web can include attribution:
attribution setting for customizing commit/PR bylines (2.0.62)Sources: CHANGELOG.md120-121 CHANGELOG.md167 CHANGELOG.md143 CHANGELOG.md278 CHANGELOG.md623 CHANGELOG.md638
| Command | Purpose | Context |
|---|---|---|
/resume | Interactive session picker | REPL |
/resume <name> | Resume named session | REPL |
/rename | Assign custom name to session | REPL |
/tag | Add tags to session | REPL |
/clear | Clear current session history | REPL |
/teleport | Resume remote session (subscribers) | REPL |
/remote-env | Configure remote session | REPL |
--resume | Resume last session | CLI |
--continue / -c | Resume in same directory | CLI |
--resume <name> | Resume by name | CLI |
--fork-session | Fork current session | CLI |
--session-id <id> | Specify custom session ID | CLI |
--from-pr <pr> | Resume by PR number/URL | CLI |
The /resume command provides:
Sources: CHANGELOG.md613
When exiting a session, Claude Code displays a hint showing how to resume:
Session can be resumed with: claude --resume
This feature was added in version 2.1.31 to improve user experience.
Claude Code includes a guard against launching within another session:
Multiple safeguards prevent duplicate sessions:
Sources: CHANGELOG.md78 CHANGELOG.md5 CHANGELOG.md110 CHANGELOG.md200
Sessions validate transcript files on resume:
parentUuid referencesSessions verify context state:
Sources: CHANGELOG.md101 CHANGELOG.md82 CHANGELOG.md98
Users can maintain multiple independent sessions:
Figure 8: Multi-Session Management
By Feature:
By Project:
By Task:
The VS Code extension provides enhanced session management:
Figure 9: VS Code Session Management
Sources: CHANGELOG.md209 CHANGELOG.md57-59 CHANGELOG.md74 CHANGELOG.md110
Significant optimizations for session management:
| Version | Optimization | Impact |
|---|---|---|
| 2.1.30 | Lightweight session index | 68% memory reduction |
| 2.0.70 | Conversation memory optimization | 3× improvement |
| 2.1.16 | Heavy subagent usage handling | Prevents OOM crashes |
| 2.1.14 | Stream resource cleanup | Fixes memory leak |
Session resume startup has been optimized:
saved_hook_context unless neededSources: CHANGELOG.md106 CHANGELOG.md561 CHANGELOG.md224 CHANGELOG.md243 CHANGELOG.md463 CHANGELOG.md114
/rename "Fix authentication bug"--continue/-c when resuming in same directory/teleport for quick access to web sessionsSession Not Found:
/resume picker to browse all sessions--resume <name>Duplicate Sessions:
/resume picker to identify and clean upResume Failures:
Memory Issues:
Sources: CHANGELOG.md106 CHANGELOG.md425 CHANGELOG.md154 CHANGELOG.md224
Refresh this wiki