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