| name | checkpoint-resume |
| description | Use when resuming paused work, starting a session where a CHECKPOINT.md exists, or when the user says "continue from checkpoint", "resume", or "pick up where we left off" |
| user-invocable | true |
Checkpoint Resume
Resume work from a CHECKPOINT.md file. Rebuild full context and continue exactly
where we left off.
Process
Step 1 — Resolve the Archive Directory
Run:
COMMON_DIR=$(git rev-parse --path-format=absolute --git-common-dir)
If this command exits non-zero, abort: "Not a git repository.
checkpoint-resume requires a git repo at CWD."
Then:
ARCHIVE=$(dirname "$COMMON_DIR")/.checkpoints
This resolves to the shared .checkpoints/ directory at the main checkout root,
consistent across all worktrees.
Step 2 — Slug Derivation
Derive <current-slug> from the current branch name:
- Get branch:
git branch --show-current
- Lowercase the result.
- Replace
/ with -.
- Strip characters outside
[a-z0-9-].
- Collapse consecutive
-.
- Detached HEAD fallback: use the basename of CWD, slugified the same way.
Step 3 — Enumerate Available Checkpoints
Collect candidates:
- Active checkpoint: Check whether
CHECKPOINT.md exists at CWD. If it
does, parse its **Branch:** line.
- Archive: List
$ARCHIVE/*.md, excluding any file matching *.prev.md
(rolling same-branch backups, not paused efforts) and any file matching
*.mirror.md (linked-worktree mirrors — these are auto-found by Case C′
below, not listed as independent entries for Case D).
Step 4 — Decide Which Checkpoint to Resume
Apply the first matching case:
Case A — CHECKPOINT.md present, branch matches current
CHECKPOINT.md exists at CWD and its **Branch:** line matches the current git
branch. → Resume it. This is the normal case. Proceed to Step 5.
Case B — CHECKPOINT.md present, branch differs from current
CHECKPOINT.md exists at CWD but its **Branch:** line is for a different
branch than the one you are currently on. → Flag the drift and prompt the user:
CHECKPOINT.md is for branch <X>, but you are currently on <Y>. How would
you like to proceed?
- (a) Resume it as-is (stay on current branch, use the checkpoint from
<X>)
- (b) Archive it to
.checkpoints/<X-slug>.md first, then pick a
checkpoint from the archive
- (c) Resume a specific archived checkpoint — list the archive contents so
I can pick
Wait for the user's response before continuing.
Case C — No CHECKPOINT.md at CWD, archive has <current-slug>.md
CHECKPOINT.md does not exist at CWD, but $ARCHIVE/<current-slug>.md does
exist. → Offer to restore it:
Found an archived checkpoint for the current branch (<current-slug>).
Restore it to continue work?
On user confirmation: move (not copy) $ARCHIVE/<current-slug>.md to
CHECKPOINT.md at CWD, then proceed to Step 5. On user decline: stop and report
no active checkpoint to resume.
Case C′ — No CHECKPOINT.md at CWD, no plain slug, but archive has
<current-slug>.mirror.md
CHECKPOINT.md does not exist at CWD, $ARCHIVE/<current-slug>.md does not
exist, but $ARCHIVE/<current-slug>.mirror.md does exist (a linked-worktree
mirror written by /checkpoint-save Step 5b). → Offer to restore it:
Found a linked-worktree mirror checkpoint for the current branch
(<current-slug>). This was saved from a worktree that may have been removed.
Restore it to continue work?
On user confirmation: copy (not move) $ARCHIVE/<current-slug>.mirror.md to
CHECKPOINT.md at CWD, then proceed to Step 5. (Copy, not move — keep the
mirror in place in case the restore is tentative.) On user decline: stop and
report no active checkpoint to resume.
Case D — No CHECKPOINT.md at CWD, no slug match, archive non-empty
CHECKPOINT.md does not exist at CWD, neither $ARCHIVE/<current-slug>.md nor
$ARCHIVE/<current-slug>.mirror.md exist, but the archive contains other .md
files (excluding *.prev.md and *.mirror.md). → List the archive contents and
ask the user to pick:
No checkpoint found for the current branch. The following archived checkpoints
are available:
.checkpoints/<slug-1>.md.checkpoints/<slug-2>.md ...
Enter the number of the checkpoint to restore, or press Enter to cancel.
On pick: move (not copy) the chosen file to CHECKPOINT.md at CWD, then
proceed to Step 5. On cancel: stop and report no checkpoint restored.
Case E — No CHECKPOINT.md and empty archive
CHECKPOINT.md does not exist at CWD and the archive has no .md files
(excluding *.prev.md and *.mirror.md), and no <current-slug>.mirror.md
exists. → Report:
No checkpoint found — neither a local CHECKPOINT.md nor any archived
checkpoints exist. Nothing to resume.
Stop.
Step 5 — Resume the Checkpoint
Once a CHECKPOINT.md is confirmed at CWD (either pre-existing or moved there
in Step 4):
- Run
git status to see current working tree state.
- Run
git diff --stat to see what changed since the checkpoint was written.
- Read any memory files referenced in the checkpoint's Relevant Memories
section.
- Review the Branch, Current State, Key Decisions Made, and Open
Questions / Blockers sections — flag any drift between the checkpoint's
"Files Modified" list and actual file state.
- Summarize the restored context to the user: what was done, what decisions
were made, what is next.
- Execute the first item from the checkpoint's Next Steps list.
Invariant after Resume
After a successful resume:
CHECKPOINT.md is present at CWD and reflects the resumed effort.- For Case C and Case D restores: the archive no longer contains the restored
file — it was moved, not copied.
- For Case C′ restores (linked-worktree mirror): the archive still contains
<slug>.mirror.md — it was copied, not moved. The mirror is kept as a
safety net.
- The archive may still contain other paused efforts for other branches.
Key Principles
- Trust the checkpoint: It was written with full session context. Don't
second-guess decisions unless the user asks to revisit them.
- Flag drift: If files changed since the checkpoint was written (someone
else committed, user edited manually), call it out before proceeding.
- Ask about blockers: If the checkpoint listed open questions, check if the
user has answers before continuing.
- Clean up after: Once work is complete, delete or archive the CHECKPOINT.md
so it doesn't confuse future sessions.
