Create and restore checkpoints for long-running sessions with git-based state persistence
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
Save and restore session state for long-running development sessions. Enables recovery from crashes and continuation across sessions.
User provides:
create, list, restore, show, auto--description, --checkpoint, --jsonSave current session state with git-based file backup:
from checkpoint import CheckpointManager
manager = CheckpointManager(session_id)
metadata = manager.create(
description="Before major refactor",
session_state={"tool_calls": 127, "phase": "implementation"},
context={"current_file": "src/auth.ts", "task": "Add OAuth"}
)
This will:
git statusShow available checkpoints for the session:
/checkpoint list
Checkpoints for session session-20241209-143022-abc123:
checkpoint-003-153045
Before major refactor
Created: 2024-12-09T15:30:45
Files: 3
checkpoint-002-142530 [auto]
Auto-checkpoint after test failure
Created: 2024-12-09T14:25:30
Files: 5
checkpoint-001-140015
Initial state
Created: 2024-12-09T14:00:15
Files: 0
Restore to a previous checkpoint:
/checkpoint restore --checkpoint checkpoint-002-142530
Restored checkpoint: checkpoint-002-142530
Files restored: 5
Warnings:
- Current uncommitted changes in 2 files
Automatic checkpoints are created on certain events:
| Trigger | Description |
|---|---|
build_failure | After build command fails |
test_failure | After tests fail |
stuck_detected | When heartbeat detects stuck pattern |
phase_complete | After completing a phase in workflows |
many_changes | After significant file changes (10+ files) |
View full details of a checkpoint:
/checkpoint show --checkpoint checkpoint-002-142530
Checkpoint: checkpoint-002-142530
Description: Auto-checkpoint after test failure
Created: 2024-12-09T14:25:30
Tool calls: 85
Files modified: ['src/auth.ts', 'src/api/routes.ts', ...]
Git ref: stash@{0}
| Subcommand | Description |
|---|---|
create (default) | Create new checkpoint |
list | List all checkpoints for session |
restore | Restore to a checkpoint |
show | Show checkpoint details |
auto | Trigger auto-checkpoint |
| Flag | Description |
|---|---|
--description, -d | Checkpoint description |
--checkpoint, -c | Checkpoint ID (for restore/show) |
--session, -s | Session ID (default: current) |
--json, -j | JSON output |
User: Create a checkpoint before I start this refactor
Creating checkpoint...
Checkpoint Created: checkpoint-004-160230
Description: Manual checkpoint
Files tracked: 3
- src/components/Auth.tsx
- src/hooks/useAuth.ts
- package.json
Git backup: stash@{0}
You can restore with: /checkpoint restore --checkpoint checkpoint-004-160230
User: Restore to the checkpoint before my refactor
Analyzing current state...
You have 5 uncommitted changes
Restoring checkpoint-004-160230...
Restored Successfully:
Files restored: 3
Warnings:
- Created backup of current changes at stash@{1}
Your workspace is now at the state before the refactor.
[Build failed - TypeScript errors]
Auto-checkpoint created: checkpoint-005-161545
Trigger: build_failure
Description: Auto-checkpoint after build failure
Files: 4
This checkpoint was created automatically. You can restore with:
/checkpoint restore --checkpoint checkpoint-005-161545
Checkpoints integrate with the heartbeat monitor for intelligent auto-checkpointing:
from heartbeat import get_monitor
from checkpoint import CheckpointManager
monitor = get_monitor()
if monitor.detect_stuck().is_stuck:
# Auto-create checkpoint when stuck detected
manager = CheckpointManager(monitor.session_id)
manager.auto_checkpoint(
trigger="stuck_detected",
session_state={"tool_calls": monitor.tool_calls},
context={"stuck_indicators": monitor.detect_stuck().indicators}
)
Checkpoints are stored in:
~/.claude/popkit/checkpoints/{session_id}/
checkpoint-001-HHMMSS.json
checkpoint-002-HHMMSS.json
...
Each checkpoint JSON contains:
metadata: ID, session, timestamp, description, filessession_state: Tool calls, phase, progressfile_snapshots: SHA-256 hashes of modified filescontext: Agent memory, current task info| Component | Purpose |
|---|---|
checkpoint.py | Core checkpoint manager |
heartbeat.py | Session health monitoring |
| Git stash | File backup mechanism |
| JSON files | State persistence |
| Session ID | Checkpoint grouping |