Session Checkpoint

CRITICAL: This skill runs near context window limits. Minimize tool calls — no subagents, no file exploration. Use only conversation context. Write files in one shot.

Commands

• Save: save checkpoint {name}, save checkpoint (auto-picks name from context)
• Resume: continue, continue {name}, resume (auto-select if one checkpoint, list if many)
• Cleanup: clear checkpoint {name}, clear all checkpoints

---

Save Procedure

1. Determine Name

If user gave a name, use it.

If no name given:

• Pick a short descriptive name from the current work (2-4 words, e.g., "my-feature") and use it directly — don't ask for confirmation. The user sees the name in the output.

Sanitize final name: lowercase, replace spaces// with -, strip leading -.

2. Locate Memory Directory

Find the auto memory directory path from the system prompt line: You have a persistent auto memory directory at <path>

3. Gather State

Run in a single bash call:

git branch --show-current && git status --short | head -10 && date '+%Y-%m-%d %H:%M'

From conversation context, determine:

• What was accomplished this session
• What failed or was abandoned (and why)
• Where work left off — don't infer next steps, but DO capture all actionable context the next session needs: pending decisions, proposed options, open questions
• Which files were modified

4. Find Active Plan

If the system prompt or conversation already references a plan file (~/.claude/plans/*.md), note its path and determine step N of M. Otherwise skip. Do NOT search for or glob plan files.

5. Write Checkpoint File

If checkpoint-{name}.md already exists, use AskUserQuestion to confirm — show the existing checkpoint's Saved date and Left Off summary, with options: "Overwrite" / "Different name" (user provides new name via "Other"). If they choose a different name, continue from this step with the new name.

Write <memory_dir>/checkpoint-{name}.md:

# Checkpoint: {name}

- **Branch:** `{branch}`
- **Saved:** {YYYY-MM-DD HH:MM}
- **Plan:** `~/.claude/plans/{file}` (step N of M)

## Left Off
{1-3 lines describing where work stopped}

## Done This Session
- {accomplishments}

## Failed Approaches
- {what + why — or "None"}

## Modified Files
- {list}

Omit the Plan: line if no plan file exists.

6. Update MEMORY.md Index

Always use Edit (not Write) for MEMORY.md changes — parallel sessions would clobber each other with Write.

Read MEMORY.md. Find the ## Active Checkpoints section.

• If checkpoint name already in index: update its line.
• If not: add a new bullet.
• If no ## Active Checkpoints section exists: insert it after the first # heading. If MEMORY.md doesn't exist, create it with # Project Memory as the heading.

Bullet format:

- **{name}** ({branch}, {Mon DD}) — {one-line summary}

Keep the Resume any: `continue` or `continue {name}` line after the bullets.

Do NOT touch any other sections in MEMORY.md.

7. Output

Keep output minimal — this often runs near end of context window.

Checkpoint "{name}" saved. Resume anytime: `continue {name}`

That's it. Don't ask follow-up questions. Don't suggest /compact or /clear — the user manages their own context window.

---

Resume Procedure

1. Determine Name

If user gave a name, use it. If no name given:

• List checkpoint-*.md files in memory directory
• If exactly one: use it automatically
• If multiple: use AskUserQuestion with checkpoint names as options (include branch and date in each option's description)
• If none: report "No saved checkpoints found." and stop

2. Read Checkpoint File

Read <memory_dir>/checkpoint-{name}.md. If file missing: remove the orphaned bullet from MEMORY.md's ## Active Checkpoints, report "Checkpoint file missing (cleaned up stale entry)", and stop.

3. Check Branch

git branch --show-current

If current branch differs from checkpoint's branch, warn:

Warning: You're on `{current}` but checkpoint was saved on `{saved}`. Switch with: git checkout {saved}

Continue regardless — user decides.

4. Load Plan

If checkpoint references a plan file, read it.

5. Present and Begin

Output the checkpoint summary and last context. If Failed Approaches is non-empty, include them:

⚠ Previously failed: {approach} — {why}

6. Auto-Clear

The checkpoint is now consumed — context is live. Delete the checkpoint file and remove its bullet from MEMORY.md's ## Active Checkpoints (same as Cleanup steps 1-2). If no bullets remain, remove the entire section.

Do NOT mention the cleanup to the user. They see only the summary from step 5, then wait for their direction.

---

Cleanup Procedure

1. Delete File

Remove the checkpoint file via Bash:

rm <memory_dir>/checkpoint-{name}.md

2. Update MEMORY.md

Remove the bullet for {name} from ## Active Checkpoints. If no bullets remain, remove the entire section (header + resume line).

3. Output

Cleared checkpoint "{name}"

clear all checkpoints

Glob checkpoint-*.md in memory directory. Delete all matches. Remove the entire ## Active Checkpoints section (header + bullets + resume line) from MEMORY.md. Output:

Cleared {N} checkpoint(s)