| name | context-save |
| version | 3.0.0 |
| description | Pre-compaction context preservation. Saves session state to files including spec file progress.
Manual: PreCompact hook handles basic saves automatically. Invoke /context-save for thorough manual save at milestones.
|
| allowed-tools | ["Read","Write","Edit","Bash","Glob"] |
Context Save
Save current session state before compaction or at a milestone.
Guard: Save files are session-specific: $STATE_DIR/auto-context-save-{session-id}.md (session ID = 8-char suffix of daily note filename). Read your session's existing save file first. If it has more detail than what you're about to write (e.g., from a previous manual save this session), merge: keep the more detailed Goal and Critical Context, union the Decisions and Key Files tables, update Status checkboxes to current state.
Save coordination: Write the semantic save only to $STATE_DIR/auto-context-save-{session-id}.md. The PreCompact hook exclusively owns $STATE_DIR/auto-context-save-{session-id}-hook.md and its per-window copies, which hold fresh mechanical state (Git/Specs/Daily Notes). Both files survive and /context-resume reads them together. Keep the ## Goal, ## Decisions, and ## Critical Context headings byte-intact because the post-compaction restore extracts them by name.
When remaining context is scarce, persist in recoverability order: (1) update the active spec's >> Current Step, (2) append new JSONL semantic events, (3) merge Goal, Next Actions, and Critical Context into the semantic save, then (4) fill the remaining tables. The hook independently preserves fresh mechanical state.
Avoid these - they cause real problems:
- Don't overwrite with less detail - a previous manual save this session may have richer context than the current state. Merging preserves information; overwriting destroys it.
- Don't list every file changed - after compaction, the model reads this file. A 50-file list wastes tokens and obscures what matters. Summarize by area (e.g., "12 files in src/components/") if >10 files.
- Don't include sensitive data - save files are plaintext in the repo. Passwords, API keys, and tokens in the save file are a security leak.
- Don't skip Next Actions - this section is the primary driver for post-compaction resumption. Without it, the model has to re-derive what to do next, which wastes time and risks going in a different direction.
Step 1: Gather State
Step 1: Gather State
Session Info
- What was the goal this session?
- What decisions were made and why?
- What files were created/modified?
- What's the current task status?
Classify Session Type (pick 1-2)
| Type | Signal |
|---|
| debugging | Hunting a bug, running tests repeatedly, narrowing a hypothesis |
| implementing | Working through a spec, building a feature, refactoring |
| exploring | Open-ended research, surveying code, weighing approaches |
| writing | Drafting prose where voice or register matters across revisions |
| experimenting | Comparing data or ML runs across configurations |
| dispatching | Orchestrating lanes, workers, or panes with results pending |
Git State
git branch --show-current 2>/dev/null || echo "not a git repo"
git status --short 2>/dev/null | head -20
git log --oneline -5 2>/dev/null
git diff --stat 2>/dev/null | tail -5
Background Tasks
Check for running agents or background shells.
Spec Files
Check for active implementation specs:
ls $SPECS_DIR/*.md 2>/dev/null
If found, read them. For each spec with Status: in-progress:
- Record the file path
- Extract the
>> Current Step section (this is the compaction lifeline)
- Count completed vs total steps
- Before saving, update the spec's
>> Current Step to reflect current state
Step 2: Write Save File
Step 2: Write Save File
Create/update $STATE_DIR/auto-context-save-{session-id}.md:
The save has two layers in this order: Core (always) and Conditional (one or two blocks matching the classified session type).
Core blocks (always include)
# Context Save - [DATE TIME]
## Goal
[Primary objective this session]
## Status
- [x] Completed items
- [ ] In progress
- [ ] Pending
## Decisions
| Decision | Reasoning |
|----------|-----------|
| [choice] | [why] |
## Key Files Modified
| Path | What changed |
|------|-------------|
| [path] | [change] |
## Git State
- Branch: [name]
- Uncommitted: [count] files
- Recent commits: [last 5 one-liners]
## Spec Files
| Path | Progress |
|------|----------|
| [spec path] | [X/Y complete] |
## Next Actions
1. [First priority]
2. [Second]
3. [Third]
## Critical Context
[Non-obvious things that would be bad to forget]
Conditional blocks
Read references/session-type-blocks.md, copy one or two templates matching the classified session type after the Core blocks, and fill every field.
Append JSONL Semantic Events
After writing the markdown save, append semantic events to $STATE_DIR/session-events-{session-id}.jsonl. These capture agent-level understanding that the PostToolUse hook cannot detect:
JSONL="$STATE_DIR/session-events-{session-id}.jsonl"
Append one JSON line per event using Bash echo >>:
- Goal:
{"type":"goal","ts":"ISO8601","sid":"...","text":"[session objective]"}
- Each decision:
{"type":"decision","ts":"ISO8601","sid":"...","what":"[choice]","why":"[reasoning]"}
- Milestone:
{"type":"milestone","ts":"ISO8601","sid":"...","text":"[status summary, e.g. Phase 1 complete, 3/7 steps done]"}
Only append events that are NEW since the last /context-save. Check the existing JSONL for duplicate goals/decisions before appending.
Quality Self-Check
After writing the save file, verify:
- Next Actions non-empty - does it have at least 1 concrete action?
- Goal is specific - does it describe the actual objective, not just "working on X"?
- Critical Context captured - any non-obvious state that would be lost in compaction?
- Spec files listed - if any exist, are they referenced with progress counts?
- JSONL events appended - did you write goal + decisions + milestone to the event log?
- Conditional blocks match session type - are one or two applicable templates filled with current state?
Step 3: Output
CONTEXT SAVED to $STATE_DIR/auto-context-save-{session-id}.md
Git: [branch] - [uncommitted count] files
Next: [top priority action]
Ready to compact.
Keep it brief.
