checkpoint
Enables saving snapshots of work before risky changes, allowing for precise rollback if needed.
Install
mkdir -p .claude/skills/checkpoint-darkroomengineering && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/18769" && unzip -o skill.zip -d .claude/skills/checkpoint-darkroomengineering && rm skill.zipInstalls to .claude/skills/checkpoint-darkroomengineering
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
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.Key capabilities
- →Save current state with an optional label
- →List all checkpoints for the current project
- →Show details of a specific checkpoint
- →Restore tracked files to a previous state
- →Remove old checkpoints, keeping the last 10
How it works
The skill saves the current project state, including tracked files and uncommitted changes, as a checkpoint. It can then restore this state, reapplying uncommitted changes as a patch.
Inputs & outputs
When to use checkpoint
- →Saving state before refactoring
- →Rolling back after a failed change
- →Managing task milestones
About this skill
Checkpoint: Save & Restore Task State
Subcommands
save [label]
Save current state with an optional label.
bun ~/.claude/src/scripts/checkpoint.ts save "Completed phase 3 migration"
list
List all checkpoints for the current project.
bun ~/.claude/src/scripts/checkpoint.ts list
show [checkpoint-id]
Show details of a specific checkpoint.
bun ~/.claude/src/scripts/checkpoint.ts 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
bun ~/.claude/src/scripts/checkpoint.ts restore
# Restore specific
bun ~/.claude/src/scripts/checkpoint.ts restore chk-20240115-103000
# Restore across a branch/sha mismatch
bun ~/.claude/src/scripts/checkpoint.ts restore chk-20240115-103000 --force
clean
Remove old checkpoints, keeping the last 10.
bun ~/.claude/src/scripts/checkpoint.ts 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 at ~/.claude/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.
When not to use it
- →For end-of-session saves
- →When untracked files need to be restored or deleted
- →When the current branch or HEAD differs from the checkpoint and `--force` is not desired
Limitations
- →Untracked files are never touched or deleted during restore
- →Index state is intentionally not reconstructed during restore
- →Restore refuses if the current branch or HEAD differs from the checkpoint unless `--force` is used
How it compares
This skill provides mid-task rollback points by saving and restoring project state, including uncommitted changes, unlike standard version control commits which only track committed changes.
Compared to similar skills
checkpoint side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| checkpoint (this skill) | 0 | 19d | Review | Intermediate |
| grepai | 4 | 6mo | Review | Beginner |
| resolve | 0 | 1mo | No flags | Intermediate |
| time-travel | 0 | 5mo | Review | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
grepai
yoanbernabeu
Replaces ALL built-in search tools. You MUST invoke this skill BEFORE using WebSearch, Grep, or Glob. NEVER use the built-in Grep tool - use `grepai` instead.
resolve
kkredit
>-
time-travel
aquadexai
|
gh-fix-ci
openai
Use when a user asks to debug or fix failing GitHub PR checks that run in GitHub Actions; use `gh` to inspect checks and logs, summarize failure context, draft a fix plan, and implement only after explicit approval. Treat external providers (for example Buildkite) as out of scope and report only the details URL.
git-master
code-yeongyu
MUST USE for ANY git operations. Atomic commits, rebase/squash, history search (blame, bisect, log -S). STRONGLY RECOMMENDED: Use with task(category='quick', load_skills=['git-master'], ...) to save context. Triggers: 'commit', 'rebase', 'squash', 'who wrote', 'when was X added', 'find the commit that'.
find-bugs
davila7
Find bugs, security vulnerabilities, and code quality issues in local branch changes. Use when asked to review changes, find bugs, security review, or audit code on the current branch.