Session Checkpoint 🔖

Your 3-hour coding session just crashed. The agent lost everything. Start from zero? No. Restore from checkpoint.

The Pain

Every agent session is a crash waiting to happen.

• Context window overflow → conversation compacted → memory wiped
• Network timeout → session lost → 2 hours of work gone
• Token limit → forced restart → re-explain everything
• Agent crash → "Hi! How can I help?" → 😤

What you lose:

• Files being edited (which ones, what changes)
• Debugging approach (what you tried, what failed)
• Key decisions (why you chose X over Y)
• The bug you were hunting (where, what pattern)
• Next steps (you were about to run tests...)

The worst part: You spend 30+ minutes re-explaining what you just spent 3 hours doing.

The Solution

Session Checkpoint creates lightweight save points at critical moments. When your session crashes, restore from the last checkpoint and continue in 30 seconds.

Before Crash                          After Crash
───────────────────────────────────────────────────────────────
📍 03:15 "Found auth bug"              
│  Files: auth.ts                      
│  Tried: Sessions → race condition    
│  Next: Test JWT approach              
│                                      │
📍 03:45 "JWT working"                 │  💥 Session crashes
│  Files: auth.ts, auth.test.ts        │  You: /restore 2
│  Decided: JWT > Sessions              │  Agent reads checkpoint
│  Next: Run tests                      │  Agent: "Running tests..."
│                                      │  😊 Continue in 30 sec
📍 04:10 "Tests passing"               
│  Next: Add rate limiting             
───────────────────────────────────────────────────────────────

Quick Start

Install

# Claude Code
cp SKILL.md .claude/skills/session-checkpoint/

# OpenClaw
cp SKILL.md ~/.openclaw/workspace/skills/session-checkpoint/

# Cursor
cp SKILL.md .cursor/rules/session-checkpoint.mdc

Create Checkpoint

# Manual checkpoint
/checkpoint "Fixed auth bug, about to test"

# Auto checkpoints (every 30 min, before risky changes)
# Agent creates these automatically

Restore

# List checkpoints
/checkpoints

# Restore from checkpoint 2
/restore 2

# Or just rollback to last
/rollback

What Gets Saved

checkpoint:
  timestamp: "2026-04-30T03:45:00Z"
  summary: "JWT authentication working"
  
  context:
    active_files:        # What files you're working on
      - auth.ts          # "Implementing JWT"
      - auth.test.ts     # "Testing JWT validation"
    
    current_task: "Run test suite for auth"
    
    decisions_made:      # Why you made these choices
      - "JWT instead of sessions — race condition in sessions"
      - "RS256 algorithm — more secure than HS256"
    
    tried_failed:        # Don't repeat these
      - "Session approach → race condition when concurrent requests"
      - "HS256 → secret key exposure risk"
    
    next_steps:          # Pick up here
      - "Run auth.test.ts"
      - "Add rate limiting to login endpoint"

Checkpoint Commands

Command	What It Does
/checkpoint "note"	Create manual checkpoint with note
/checkpoints	List all checkpoints (show timestamps + summaries)
/restore N	Restore from checkpoint N (1 = oldest)
/rollback	Quick restore from last checkpoint
/prune	Remove old checkpoints (keep last 10 by default)

Auto-Checkpoint Triggers

Your agent creates checkpoints automatically:

Trigger	When	Why
interval	Every 30 minutes	Catch unexpected crashes
before_refactor	Before major code changes	Easy rollback if refactor fails
after_bug_found	When bug identified	Don't lose the hunt
before_risky_change	Before deletions/restructures	Safety net
on_test_failure	When tests fail	Remember what broke

Config in .session/config.json:

{
  "autoCheckpoint": true,
  "intervalMinutes": 30,
  "maxCheckpoints": 20,
  "triggers": ["before_refactor", "after_bug_found", "before_risky_change"]
}

Real Savings

Before Checkpoint	After Checkpoint
3-hour crash → 30 min re-explaining	3-hour crash → 30 sec restore
Repeat dead-end approaches	Skip tried_failed list
Re-decide on architecture	decisions_made preserved
"What was I doing?"	current_task clear
"Which files?"	active_files list

Time saved per crash: 25-45 minutes
Crashes per week (avg): 2-4
Time saved per week: 50-180 minutes

How It Works

1. Checkpoint file — Plain markdown, version controlled
2. Restore on demand — /restore N reads checkpoint into agent context
3. Auto-triggered — Agent creates checkpoints at key moments
4. Human-readable — Open .session/cp-TIMESTAMP.md anytime
5. Zero dependencies — Just files, no database

Directory Structure

.session/
├── current.md           # Active session summary
├── checkpoints/
│   ├── cp-20260430-0315.md   # "Found auth bug"
│   ├── cp-20260430-0345.md   # "JWT working"
│   └── cp-20260430-0410.md   # "Tests passing"
└── config.json          # Auto-checkpoint settings

Works With

• OpenClaw
• Claude Code
• Cursor
• Codex
• Any agent that reads markdown

Related Skills

Skill	Purpose
Session Context Bridge	Long-term session persistence
Error Recovery	Handle errors systematically
Token Budget Guard	Prevent context overflow

Why Not Context-Mode?

Context-Mode (11K★) is powerful but heavy:

• Requires MCP server installation
• SQLite database + FTS5 indexing
• 14 platforms with different configs

Session Checkpoint is lighter:

• No MCP, no database
• Just markdown files in .session/
• Works anywhere files work
• 5 seconds to create, 30 seconds to restore

Think of it as: Context-Mode for the 90% simpler cases.

License

MIT — Save your work freely.