/session-save
Capture the current session into a structured handoff file so you (or another instance) can resume with full context. Creates a timestamped Markdown file in .claude/sessions/.
When to use
- Before ending a session that isn't complete
- Before switching to a different task
- Before context reaches 75%+ (to preserve the important parts)
- At natural milestones in a long task (after each phase)
- To hand off to a second Claude instance
Instructions
Produce a handoff document with the following structure:
Session handoff: [TIMESTAMP]
What was being done
[One paragraph: the goal, the approach, where things stand right now]
Files modified this session
[List every file that was created, edited, or deleted, with the nature of the change]
path/to/file.ts - [what changed and why] path/to/other.ts - [what changed and why]
Key decisions made
[Architectural choices, tradeoffs accepted, approaches rejected and why]
- Decision: [What was decided]
- Rationale: [Why]
- Alternatives rejected: [What else was considered]
Current status
[Where things are right now: what's working, what's broken, what's in-progress]
- Working: [...]
- In-progress: [...]
- Known issues: [...]
Next steps (ordered)
[The exact next actions to take to continue, specific enough that a fresh context can pick up without re-reading everything]
- [First action]:
path/to/file.ts- [what to do] - [...]
Context to reload
[Files that must be read to resume with full understanding, keep this list short]
path/to/key-file.ts: [why it matters]CLAUDE.md: project rules
Blockers / open questions
[Anything unresolved that needs a decision or external input before proceeding]
- [Question or blocker]: [who/what can resolve it]
Implementation
Save the handoff to .claude/sessions/handoff-[YYYY-MM-DD-HHMM].md. Then output the file path so the user knows where to find it.
Resume pattern
To resume from a handoff:
/session-resume .claude/sessions/handoff-YYYY-MM-DD-HHMM.md
Or manually: read the handoff file, then read the files listed in "Context to Reload" before continuing.
Examples
Example 1: Mid-Feature save
/session-save
Claude captures:
- Auth middleware was being refactored (files:
src/middleware/auth.ts,src/middleware/jwt.ts) - Decision: switched from session tokens to JWTs (rationale: scales better across services)
- Status: JWT validation working, refresh logic in-progress
- Next: implement
refreshToken()insrc/services/auth.service.ts, then update tests
Example 2: Context-Pressure save
When context hits 70%, run /session-save before /compact to preserve decision context that compaction might lose.
Notes
- Keep "Context to Reload" to 5 files max. The goal is a fast resume, not a full re-read.
- "Next Steps" should be specific enough that a cold-start Claude can execute step 1 without asking questions
- Don't save tool output or code snippets in the handoff; reference file paths instead.
See also:
- Session Teleportation: broader session management patterns
- Instinct-Based Learning: what to extract from sessions before closing
