Learn-skills.dev checkpoint-manager

State snapshots and rollback for safe experimentation. Use when creating checkpoints, rolling back changes, managing recovery points, or implementing safe experimentation.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/adaptationio/skrillz/checkpoint-manager" ~/.claude/skills/neversight-learn-skills-dev-checkpoint-manager && rm -rf "$T"

manifest: data/skills-md/adaptationio/skrillz/checkpoint-manager/SKILL.md

source content

Checkpoint Manager

Creates and manages state checkpoints for safe rollback during autonomous coding.

Quick Start

Create Checkpoint

from scripts.checkpoint_manager import CheckpointManager

manager = CheckpointManager(project_dir)
checkpoint = await manager.create_checkpoint(
    name="before-refactor",
    description="State before major refactoring"
)

Rollback to Checkpoint

await manager.rollback(checkpoint.id)
# or rollback to latest
await manager.rollback_to_latest()

Checkpoint Workflow

┌─────────────────────────────────────────────────────────────┐
│                 CHECKPOINT WORKFLOW                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  CREATE CHECKPOINT                                           │
│  ├─ Capture git state (commit hash, dirty files)           │
│  ├─ Snapshot feature list                                   │
│  ├─ Save progress file state                               │
│  ├─ Record context (session, tokens)                       │
│  └─ Store checkpoint metadata                               │
│                                                              │
│  RISKY OPERATION                                             │
│  ├─ Attempt operation                                       │
│  ├─ If success → Continue                                   │
│  └─ If failure → Rollback to checkpoint                    │
│                                                              │
│  ROLLBACK                                                    │
│  ├─ Load checkpoint data                                    │
│  ├─ Git reset to checkpoint commit                         │
│  ├─ Restore feature list                                   │
│  ├─ Restore progress file                                  │
│  └─ Clean up temporary files                               │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Checkpoint Structure

{
  "id": "checkpoint-20250115-103000",
  "name": "before-refactor",
  "description": "State before major refactoring",
  "timestamp": "2025-01-15T10:30:00",
  "git_state": {
    "commit_hash": "abc1234",
    "branch": "main",
    "dirty_files": ["src/app.ts"]
  },
  "feature_state": {
    "current": "auth-003",
    "completed": ["auth-001", "auth-002"],
    "snapshot_path": ".claude/checkpoints/checkpoint-xxx/feature_list.json"
  },
  "context": {
    "session_number": 5,
    "token_usage": 45000
  }
}

Checkpoint Types

Type	Trigger	Retention
Automatic	Before risky operations	Last 5
Manual	User/agent request	Until deleted
Feature	After feature complete	Permanent
Session	Start of session	Last 3

Integration Points

error-recoverer: Triggers rollback on failures
coding-agent: Creates checkpoints before changes
autonomous-loop: Manages checkpoint lifecycle
context-state-tracker: Provides state to checkpoint

References

```
references/CHECKPOINT-STRATEGY.md
```
- Strategy guide
```
references/ROLLBACK-PROCEDURES.md
```
- Rollback details

Scripts

```
scripts/checkpoint_manager.py
```
- Core manager
```
scripts/git_snapshot.py
```
- Git state capture
```
scripts/state_snapshot.py
```
- Feature/progress capture
```
scripts/rollback_handler.py
```
- Rollback execution