Session Management

When To Use

Managing session checkpoints and state preservation
Resuming work across Claude Code sessions

When NOT To Use

Short sessions that do not need checkpoints
Fresh starts where no prior session context exists

Overview

Claude Code supports named sessions for better workflow organization. Use this skill to manage complex, long-running work across multiple sessions.

Available Commands

Command Description

/rename

Name the current session (auto-generates name if no argument given, 2.1.41+)

/resume

Resume a previous session (REPL)

claude --resume <name>

Resume from terminal

Workflow Patterns

Debugging Sessions

Name debug sessions for easy resumption:

Start debugging

/rename debugging-auth-issue

... work on the issue ...

If you need to pause, session is auto-saved

Resume later:

claude --resume debugging-auth-issue

Feature Development Checkpoints

Create checkpoints during long feature work:

After completing milestone 1

/rename feature-x-milestone-1

Continue in new session

Reference old session if needed

PR Review Sessions

For complex PR reviews that span multiple sittings:

Start review

/rename pr-review-123

Take breaks without losing context

Resume:

claude --resume pr-review-123

PR-Linked Sessions (Claude Code 2.1.27+)

Sessions are automatically linked to PRs when created via gh pr create . Resume PR-specific sessions later:

Resume session for a specific PR

claude --from-pr 156 claude --from-pr https://github.com/org/repo/pull/156

Workflow: review → pause → resume with full context

/rename pr-review-156

... review work ...

Later:

claude --from-pr 156

Investigation Sessions

When investigating issues that may require research:

Start investigation

/rename investigate-memory-leak

Pause to gather more info externally

Resume with full context:

claude --resume investigate-memory-leak

Resume Screen Features

The /resume screen provides:

Grouped forked sessions: See related sessions together
Keyboard shortcuts (defaults, customizable via /keybindings ):
Preview session content
Rename a session
Recent sessions: Sorted by last activity

Resume Hint on Exit (Claude Code 2.1.31+)

Claude Code now shows a resume hint when you exit, displaying the command to continue your conversation. This makes session resumption more discoverable — users no longer need to know about --resume beforehand.

Best Practices

Naming Conventions

Use descriptive, hyphenated names:

Pattern Example Use Case

debugging-<issue>

debugging-auth-401

Bug investigation

feature-<name>-<milestone>

feature-search-v2

Feature development

pr-review-<number>

pr-review-156

PR reviews

investigate-<topic>

investigate-perf

Research

refactor-<area>

refactor-api-layer

Refactoring work

When to Name Sessions

Name sessions when:

Work will span multiple days
You might need to pause unexpectedly
The session contains valuable context
You want to reference it later

Session Cleanup

Unnamed sessions are eventually garbage collected. Named sessions persist longer. Periodically clean up old named sessions you no longer need.

Integration with Sanctum

Combine session management with other Sanctum skills:

Before starting: Run Skill(sanctum:git-workspace-review) to capture context
Name the session: /rename <descriptive-name>
Work: Use appropriate skills for the task
Resume if needed: claude --resume <name>

Troubleshooting

Session Not Found

If a named session isn't appearing in /resume :

Check for typos in the name
Sessions may expire after extended inactivity
Use /resume screen to browse available sessions

Duplicate Sessions in VS Code

If you see duplicate session entries when resuming in VS Code:

Claude Code 2.1.38+: Fixed — resume now correctly reuses the existing session without creating duplicates
Older versions: Ignore the duplicate entries; they point to the same underlying session

Lost Context After Resume

If context seems incomplete or resume is slow:

Claude Code 2.1.30+: 68% memory reduction for --resume via stat-based session loading with progressive enrichment — especially impactful for users with many sessions. Also fixes hangs when resuming sessions with corrupted transcript files (parentUuid cycles).
Claude Code 2.1.29+: Fixed slow startup when resuming sessions with many once: true hooks — saved_hook_context loading is now optimized
Claude Code 2.1.21+: Fixed API errors when resuming sessions interrupted during tool execution — previously these sessions could fail to resume entirely
Claude Code 2.1.20+: Session compaction/resume is now fixed — resume correctly loads the compact summary instead of full history
Use /catchup to refresh git state
Use /debug (Claude Code 2.1.30+) for session troubleshooting diagnostics
Re-run Skill(sanctum:git-workspace-review) if needed
If on older versions: resumed sessions may reload uncompacted history, increasing context usage unexpectedly

macOS Orphaned Processes (Claude Code 2.1.46+)

Previously, disconnecting from a terminal on macOS could leave orphaned Claude Code processes running. This is now fixed in 2.1.46+. If you encounter stale CC processes on older versions, manually check and kill them:

Find orphaned claude processes

ps aux | grep -i claude | grep -v grep

Automatic Memory (Claude Code 2.1.32+)

Claude now automatically records and recalls memories as it works. Session summaries, key results, and work logs are captured implicitly and recalled in future sessions. This provides passive cross-session continuity without manual checkpoint management.

No action required: Memory recording is automatic on first-party Anthropic API
Complements named sessions: Automatic memory handles implicit continuity; named sessions provide explicit organization
Token overhead: Recalled memories add to baseline context — factor this into MECW budgets

Agent Persistence on Resume (Claude Code 2.1.32+)

--resume now re-uses the --agent value from the previous conversation by default. Agent-specific workflows that are resumed will continue with the same agent configuration without needing to re-specify it.

Start with a specific agent

claude --agent my-agent

Resume later — my-agent is automatically used

claude --resume

session-management

Safety Notice

Copy this and send it to your AI assistant to learn