# Checkpoint

> Save current progress to a checkpoint file. Use before context-heavy operations or as regular backup.

- Skill: `fanlw0816/checkpoint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fanlw0816/checkpoint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fanlw0816/checkpoint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: fanlw0816 (https://skillmd.com/u/fanlw0816)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fanlw0816/checkpoint

---


# Checkpoint Skill

You are saving session progress to a checkpoint file. This enables resumption after context compaction, session end, or context reset.

## Purpose

Checkpoints provide:
- Work continuity across sessions
- Recovery from context loss
- Progress backup before risky operations
- Handoff preparation for context reset

## When to Checkpoint

**Automatic Triggers:**
- Before major refactoring
- After completing significant work
- Before context-heavy operations
- Pre-compact hook (automatic)

**Manual Triggers:**
- User calls `/checkpoint`
- Before ending a session
- When switching tasks mid-stream

## Checkpoint Process

```
/checkpoint [message]
     |
     +--[1] Gather session state
     |       - Current task
     |       - Files modified
     |       - Decisions made
     |       - Open questions
     |
     +--[2] Write checkpoint file
     |       - .claude/checkpoint.md
     |       - Timestamp
     |       - Full context dump
     |
     +--[3] Confirm save
             - Show summary
             - Offer to continue or exit
```

## Checkpoint File Structure

```markdown
# Checkpoint: [timestamp]

## Session Info
- Started: [session start time]
- Saved: [checkpoint timestamp]
- Duration: [elapsed time]

## Current Task
[Description of active task]

## Work Completed
### Done
- [item 1]
- [item 2]

### In Progress
- [item 3] - [status/notes]

### Blocked
- [item 4] - [blocker description]

## Files Modified
| File | Status | Changes |
|------|--------|---------|
| path/to/file.py | modified | [summary] |
| path/to/other.py | created | [summary] |

## Key Decisions
1. [Decision] - [rationale]
2. [Decision] - [rationale]

## Open Questions
- [question 1] - [context/impact]
- [question 2] - [context/impact]

## Next Steps
1. [immediate next action]
2. [following action]
3. [future consideration]

## Commands to Resume
```bash
# To resume this checkpoint:
/resume [checkpoint-id]

# Or run:
/start
```

## Context Snapshot
```
[Recent conversation summary - key points only]
```

## Git State
- Branch: [current branch]
- Uncommitted: [yes/no - count of files]
- Last commit: [hash] [message]
```

## Implementation Steps

### Step 1: Collect Context

```
1. Read conversation history (last N exchanges)
2. Identify active task from context
3. List all files read/modified this session
4. Capture key decisions and rationale
5. Note open questions and blockers
```

### Step 2: Generate Checkpoint

```
1. Create checkpoint directory if needed
2. Write checkpoint file with timestamp
3. Include all sections from template
4. Add git status if in repo
```

### Step 3: Confirm

```
CHECKPOINT SAVED

ID: checkpoint-[timestamp]
File: .claude/checkpoint.md

Summary:
- Task: [active task]
- Files: [count] modified
- Duration: [session duration]

Options:
1. Continue working
2. End session (checkpoint preserved)
3. Create handoff artifact (for context reset)
```

## Checkpoint Management

### Checkpoint Rotation

Keep last N checkpoints (configurable, default 5):
```
.claude/
  checkpoints/
    checkpoint-2024-01-15-001.md
    checkpoint-2024-01-15-002.md
    checkpoint-2024-01-15-003.md  (newest)
```

### Checkpoint Cleanup

- Auto-delete checkpoints older than 7 days
- Keep named checkpoints indefinitely
- Archive checkpoints when handoff created

## Integration with Context Reset

Before context reset, checkpoint automatically:
```
1. /checkpoint "pre-context-reset"
2. Create handoff artifact from checkpoint
3. Fresh session loads handoff
4. Continue without lost context
```

## Usage

```
/checkpoint                    # Save with auto-message
/checkpoint "pre-refactor"     # Save with description
/checkpoint --named "v1"       # Save named checkpoint
/checkpoint --list             # List all checkpoints
```

## Output

```
CHECKPOINT CREATED

ID: cp-2024-01-15-143052
File: .claude/checkpoints/cp-2024-01-15-143052.md

Task: Implementing user authentication
Progress: 60% complete
Files: 4 modified, 2 created

Resume with: /resume cp-2024-01-15-143052
```

## Error Handling

```
CHECKPOINT FAILED

Error: [error description]
Recovery: [suggested fix]

Partial save available at: .claude/checkpoint-partial.md
Manual intervention may be needed.
```

## Integration Points

- **With /start**: Loads checkpoints on session start
- **With /resume**: Loads specific checkpoint by ID
- **With pre-compact hook**: Called automatically before context compaction
- **With session-stop hook**: Saves final checkpoint on session end