| name | save-session |
| description | Save current session state for handoff to a future session. Creates a structured file capturing what worked, what failed, and the exact next step. Use when stepping away, before cache expires, or when context is getting heavy. Part of claude-cost-helpers (idle-tax). |
Save Session
Capture everything from this session so the next one can pick up exactly where this one left off. The "What Did NOT Work" section is the most critical — without it, the next session will blindly retry failed approaches.
Process
Step 1: Gather context
Before writing, collect:
- All files modified this session (check
git diff or recall from conversation)
- What was discussed, attempted, and decided
- Errors encountered and how they were resolved (or not)
- Current test/build status if relevant
Step 2: Create the session file
mkdir -p ~/.claude/sessions
Create ~/.claude/sessions/YYYY-MM-DD-<short-description>-session.md using today's date and a lowercase-hyphenated description (e.g., 2026-03-16-drupal-migration-session.md).
Step 3: Write every section honestly
Do not skip sections — write "None" or "N/A" if a section has no content. An incomplete file is worse than an honest empty section.
Step 4: Show the file to the user
Display the full contents and ask: "Does this look accurate? Anything to correct or add?"
Session File Format
# Session: YYYY-MM-DD
**Project:** [project name or path]
**Topic:** [one-line summary]
**Branch:** [git branch if applicable]
---
## What We Are Building
[1-3 paragraphs with enough context that someone with zero memory can understand the goal.]
---
## What WORKED (with evidence)
- **[thing]** — confirmed by: [specific evidence]
If nothing confirmed: "Nothing confirmed working yet."
---
## What Did NOT Work (and why)
- **[approach tried]** — failed because: [exact reason / error message]
If nothing failed: "No failed approaches yet."
---
## What Has NOT Been Tried Yet
- [approach / idea with enough detail to act on]
---
## Current State of Files
| File | Status | Notes |
|------|--------|-------|
| `path/to/file` | Complete / In Progress / Broken / Not Started | [details] |
---
## Decisions Made
- **[decision]** — reason: [why chosen over alternatives]
---
## Blockers & Open Questions
- [blocker / question]
---
## Exact Next Step
[The single most important thing to do when resuming. Be precise enough that resuming requires zero thinking about where to start.]
Notes
- Each session gets its own file — never append to a previous session's file
- "What Did NOT Work" is the most critical section — prevents wasting time on dead ends
- If saving mid-session, mark in-progress items clearly
Companion Hook
This skill is part of the Idle Tax helper (idle-tax). The companion hook (cache-idle-timer.sh) warns when your prompt cache has expired after 5+ minutes of inactivity. Install the hook for automatic warnings: cd idle-tax && ./install.sh
