Session Checkpoint

Create a checkpoint of current work to prevent context overflow and enable seamless session resumption.

When to Use

Trigger checkpoint when:

• Context feels long (50+ message exchanges)

• Multi-agent orchestration session

• Complex multi-phase work

• Before major phase transitions

• User says "checkpoint" or "save progress"

• You estimate >60% context usage

Don't wait until context is full - checkpoint proactively!

Checkpoint Process

1. Create Checkpoint File

Write to: .claude/checkpoints/YYYY-MM-DD-[topic].md

Template:

Session Checkpoint: [Topic/Task Name]

Date: [timestamp] Status: [in-progress / blocked / ready-for-next-phase / needs-review] Context Used: [estimate: low/medium/high]

Executive Summary

[2-3 sentences: What was the goal? What's been accomplished? What's remaining?]

Completed ✅

• [Task 1 with key details]
• [Task 2 with key details]
• [Decision made: X approach chosen because Y]

In Progress 🔄

• [Current step being worked on]
• [What's partially done]

Blockers 🛑

• [Blocker 1: description and what's needed to unblock]
• [None if no blockers]

Next Steps 📋

1. [Next action item with enough detail to start fresh]
2. [Second action]
3. [Third action]

Key Context to Preserve

Working Directory: [absolute path]

Modified Files:

• [file 1] - [what changed]
• [file 2] - [what changed]

Data Locations:

• MCP query results: [path if saved to disk]
• Temporary files: [paths]
• Database state: [any relevant info]

Environment/Configuration:

• [Any non-obvious state that matters]
• [API keys loaded, services running, etc.]

Decisions Made:

• [Decision 1: Why we chose approach X over Y]
• [Decision 2: Trade-offs accepted]

Learnings/Patterns:

• [New pattern discovered]
• [Thing that should go in CLAUDE.md]

Resume Instructions

To resume this work:

# Read checkpoint
Read .claude/checkpoints/[this-file].md

# Resume from Phase [N]
[Specific next command or action to take]

Context needed:

- [What files to read first]

- [What state to verify]

Related Files

- [Link to related docs]

- [Link to related code]

- [Link to previous checkpoint if iterative work]

### 2. Update CLAUDE.md If Learnings

If you discovered new patterns, anti-patterns, or rules during this session:
- Add them to CLAUDE.md "Critical Behavioral Rules" or relevant section
- Document in checkpoint what was added

### 3. Report to User

✅ Checkpoint saved: .claude/checkpoints/[filename].md

Session Summary:

- Completed: [X tasks]

- Current: [working on Y]

- Remaining: [Z tasks]

- Context estimate: [60% / 70% / etc]

Options:

- Continue in this session (if context allows)

- Start fresh session: "Read .claude/checkpoints/[file] and continue from [phase]"

- Review checkpoint and plan next steps

What would you like to do?

## Checkpoint Quality Checklist

Before finalizing checkpoint, verify:

- ✅ Someone else (or future-you) could resume work from this doc alone
- ✅ All decisions explained (not just "chose X" but "chose X because Y")
- ✅ File paths are absolute and correct
- ✅ Next steps are actionable (not vague like "continue working")
- ✅ Any data/state is either saved to disk or documented where to re-query it
- ✅ Learnings captured (for CLAUDE.md or future reference)

## Advanced: Multi-Checkpoint Projects

For very large projects spanning many sessions:

**Structure:**

.claude/checkpoints/
project-name/
001-initial-research.md
002-architecture-decisions.md
003-phase-1-implementation.md
004-phase-1-testing.md
CURRENT.md -> symlink to latest

**Maintain a checkpoint index:**
`.claude/checkpoints/project-name/INDEX.md` that lists all checkpoints chronologically.

## Integration with GSD

If using GSD workflow:
- Checkpoint aligns with phase boundaries
- Reference GSD phase number in checkpoint
- Link to relevant PLAN.md or ROADMAP.md files
- Include current phase status from GSD

Example:

GSD Context

- Current Phase: 3.2 (Implement user authentication)

- Phase Status: 60% complete

- Plan: .planning/phases/phase-3/PLAN.md

- Roadmap: .planning/ROADMAP.md

## When NOT to Checkpoint

Skip checkpointing for:
- Very short sessions (<10 messages)
- Simple tasks with no state
- Already at end of work (just finish instead)
- User explicitly wants to power through in one session