Checkpoint

Skill darkroomengineering/cc-settings/skills/checkpoint

Mid-task rollback points — save/restore state before risky ops (refactors, migrations, destructive edits). For end-of-session save use `/handoff`. Triggers "checkpoint", "snapshot", "before this risky op", "rollback to", "list checkpoints", pre-refactor save.From its SKILL.md

Install

npx -y skills add darkroomengineering/cc-settings --skill checkpoint

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

SKILL.md

3.9 KB, as published. Nobody here has run it

Checkpoint: Save & Restore Task State

Product-aware runner

Set these once for the active host. checkpoint.ts uses claudePath, so pass the matching state root on every invocation.

# Standalone Codex
CHECKPOINT_RUNNER="${CODEX_HOME:-$HOME/.codex}/darkroom/source/src/scripts/checkpoint.ts"
CC_STATE_ROOT="${CODEX_HOME:-$HOME/.codex}/darkroom/state"

# Claude Code instead uses:
# CHECKPOINT_RUNNER="$HOME/.claude/src/scripts/checkpoint.ts"
# CC_STATE_ROOT="$HOME/.claude"

Subcommands

save [label]

Save current state with an optional label.

CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$CHECKPOINT_RUNNER" save "Completed phase 3 migration"

list

List all checkpoints for the current project.

CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$CHECKPOINT_RUNNER" list

show [checkpoint-id]

Show details of a specific checkpoint.

CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$CHECKPOINT_RUNNER" show chk-20240115-103000

restore [checkpoint-id] [--force]

Real, opt-in rollback — restores tracked files (working tree + index) to exactly what they were at save time, then reapplies whatever uncommitted changes existed at that moment (captured as a patch when the checkpoint was saved). Untracked files are never touched or deleted; if any existed at save time they're just listed as a warning (their content was never captured). Scope note: restore reconstructs file content only — anything that was staged at save time comes back as unstaged working-tree changes (the patch reapplies to the worktree; index state is intentionally not reconstructed).

Safety rails:

Auto safety-checkpoint first. Before anything is touched, the current state is saved as its own checkpoint and its id is printed — restore is itself reversible by restoring that id (with --force).
Branch/sha guard. If the current branch or HEAD differs from what the checkpoint recorded, restore refuses and tells you to check out that branch or pass --force.
Legacy checkpoints (saved before this patch-capture feature existed) have no recorded diff to restore from. Restoring one prints "legacy checkpoint: metadata only, nothing restored" and falls back to the old print-only behavior — review the dumped JSON and continue manually.

# Restore latest
CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$CHECKPOINT_RUNNER" restore

# Restore specific
CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$CHECKPOINT_RUNNER" restore chk-20240115-103000

# Restore across a branch/sha mismatch
CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$CHECKPOINT_RUNNER" restore chk-20240115-103000 --force

clean

Remove old checkpoints, keeping the last 10.

CC_SETTINGS_HOME="$CC_STATE_ROOT" bun "$CHECKPOINT_RUNNER" clean

Examples

User: "save a checkpoint"
  -> /checkpoint save

User: "checkpoint before this refactor"
  -> /checkpoint save "Before auth refactor"

User: "list my checkpoints"
  -> /checkpoint list

User: "restore from last checkpoint"
  -> /checkpoint restore

User: "show checkpoint details"
  -> /checkpoint show <id>

User: "clean up old checkpoints"
  -> /checkpoint clean

Storage

Checkpoints are stored under $CC_STATE_ROOT/checkpoints/<project-name>/ as JSON files with a latest symlink pointing to the most recent. Each checkpoint with uncommitted changes at save time also gets a sibling chk-<id>.patch file (git diff HEAD output) — this is what makes restore a real rollback instead of a metadata dump. Checkpoints saved before this feature existed have no patch file and restore in metadata-only (legacy) mode.