Checkpoint

Checkpoint

Shadow git checkpoint system that snapshots and restores working directory state using an isolated git repository. The project's .git history is never touched.

Skill type: Rigid — follow exactly, no shortcuts.

Execution model: No modes, no subagent dispatch. The consuming orchestrator (build, quality-gate, debugging) follows these instructions directly when taking or restoring checkpoints.

Shadow Repository Setup

Initialize once per session, on first checkpoint request:

1. Compute directory hash: SHA-256 of the absolute working directory path, truncated to 16 characters.

`` echo -n "/absolute/path/to/project" | sha256sum | cut -c1-16 ``

1. Shadow repo path: ~/.claude/projects//checkpoints//

1. Initialize: If the shadow repo does not exist:

``bash GIT_DIR= GIT_WORK_TREE= git init ``

1. Write .gitignore in the shadow repo (not the project):

`` node_modules/ .env .env.* __pycache__/ .git/ venv/ .venv/ dist/ build/ .next/ *.pyc .DS_Store ``

1. Health check: Before every operation, verify:

``bash GIT_DIR= git rev-parse --git-dir `` If this fails, reinitialize the shadow repo and warn: "Shadow repo was corrupt — reinitialized. Prior checkpoints are lost."

Tool constraint: All shadow repo operations MUST use the Bash tool with explicit GIT_DIR and GIT_WORK_TREE environment variables. Never use Write/Read/Glob for shadow repo git operations. Never run git commands without these env vars — bare git commands would affect the project repo.

Pre-Check: Directory Size

Before the first checkpoint in a session, count files in the working directory (excluding ignored paths):

find  -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/__pycache__/*' -not -path '*/venv/*' -not -path '*/.venv/*' -type f | wc -l

If count exceeds 50,000: skip all checkpoints for this directory with warning "Directory has >50,000 files — checkpoints disabled for performance." Cache this decision for the session (do not re-count).

Create Checkpoint

1. Deduplication: Read the latest commit timestamp from the shadow repo:

``bash GIT_DIR= git log -1 --format=%ct 2>/dev/null `` If the current time minus the commit timestamp is less than 1 second, skip this checkpoint (deduplication).

1. Stage all files:

``bash GIT_DIR= GIT_WORK_TREE= git add -A ``

1. Commit:

``bash GIT_DIR= GIT_WORK_TREE= git commit -m " | | " --allow-empty-message ` The is a structured string (e.g., pre-design-gate, pre-wave-3, pre-qg-fix-round-2). The ` is the consuming skill name (build, quality-gate, debugging).

1. Record the commit hash as the checkpoint ID.

1. Update manifest: Append an entry to checkpoint-manifest.md in the shadow repo directory (outside the git tree):

`` | | | | | ``

1. Eviction: After commit, count entries in checkpoint-manifest.md. If count exceeds 50 (configurable — orchestrators may override), remove the oldest entries from the manifest. Git objects for evicted commits are cleaned up by the Prune step.

List Checkpoints

Read checkpoint-manifest.md from the shadow repo directory. Display in most-recent-first order:

| Hash     | Timestamp           | Reason              | Source       |
|----------|---------------------|----------------------|--------------|
| a1b2c3d4 | 2026-03-24 12:45:30 | pre-wave-3           | build        |
| e5f6g7h8 | 2026-03-24 12:30:15 | pre-plan-gate        | build        |

Restore (Full Directory)

1. Create a pre-restore safety checkpoint with reason pre-restore-safety and source checkpoint. This enables "undo the undo."

1. Restore:

``bash GIT_DIR= GIT_WORK_TREE= git checkout -- . ``

1. Verify: Run the project's test suite or relevant subset to confirm the restored state is healthy.

1. Report: "Restored to checkpoint ` (). Safety checkpoint created at ` — use this to undo the restore."

Restore (Single File)

1. Create a pre-restore safety checkpoint with reason pre-restore-safety-file and source checkpoint.

1. Restore:

``bash GIT_DIR= GIT_WORK_TREE= git checkout -- ``

1. Report: "Restored ` from checkpoint (`)."

Prune

Run at session start (before first checkpoint) to reclaim space:

1. ```bash

GITDIR= GITWORK_TREE= git gc --prune=now ```

1. Read checkpoint-manifest.md and verify each entry's hash exists:

``bash GIT_DIR= git cat-file -t `` Remove entries with invalid hashes (orphaned by prior gc).

Compaction Recovery

The checkpoint manifest and shadow repo persist across compaction because they live in ~/.claude/projects/ (not in /tmp/ or in-memory).

After compaction:

1. Recompute the directory hash from the current working directory path
2. Check if ~/.claude/projects//checkpoints// exists
3. If yes: read checkpoint-manifest.md to recover available checkpoints
4. If no: checkpoints are unavailable for this session (no error — the pipeline continues without checkpoint protection)

No active marker file is needed — the shadow repo's existence IS the marker. The directory hash computation is deterministic from the working directory path.

Red Flags

• NEVER modify the project's .git directory
• NEVER run git commands without GIT_DIR and GIT_WORK_TREE env vars
• NEVER take a checkpoint mid-wave — wait for all parallel agents to complete before snapshotting
• NEVER auto-restore without user confirmation — always present restore as an option, not an action
• NEVER delete the shadow repo without explicit user request

Integration

Consuming skills:

• crucible:build — Pipeline boundary checkpoints (pre-design-gate, pre-plan-gate, pre-wave-N, pre-cleanup-task-N, pre-temper, pre-inquisitor, pre-impl-gate)
• crucible:quality-gate — Pre-fix-round checkpoints for code artifacts (pre-qg-fix-round-N)
• crucible:debugging — Pre-implementation, pre-sibling, and pre-quality-gate checkpoints (pre-debug-fix-cycle-N, pre-where-else, pre-debug-gate)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: raddue
• Source: raddue/crucible
• License: MIT

Install and usage instructions live in the source repository linked above.