From crucible
Creates shadow git checkpoints of working directories for rollback in build, quality-gate, and debugging pipelines without modifying project git history.
npx claudepluginhub raddue/crucibleThis skill uses the workspace's default tool permissions.
Shadow git checkpoint system that snapshots and restores working directory state using an isolated git repository. The project's `.git` history is never touched.
Manages Gemini CLI checkpointing with git snapshots, /restore for listing and restoring states, rollback, and config for experimental workflows.
Auto-quicksaves files before destructive bash commands (rm, mv, git reset); manual checkpoints, diffs, lists, and restores for safe file recovery.
Safely rolls back to previous octo-checkpoint git tags. Lists checkpoints, previews file changes, requires 'ROLLBACK' confirmation, creates safety backup, preserves lessons in .octo/LESSONS.md.
Share bugs, ideas, or general feedback.
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.
Initialize once per session, on first checkpoint request:
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
Shadow repo path: ~/.claude/projects/<project-hash>/checkpoints/<dir-hash>/
Initialize: If the shadow repo does not exist:
GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git init
Write .gitignore in the shadow repo (not the project):
node_modules/
.env
.env.*
__pycache__/
.git/
venv/
.venv/
dist/
build/
.next/
*.pyc
.DS_Store
Health check: Before every operation, verify:
GIT_DIR=<shadow-path> 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.
Before the first checkpoint in a session, count files in the working directory (excluding ignored paths):
find <working-dir> -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).
Deduplication: Read the latest commit timestamp from the shadow repo:
GIT_DIR=<shadow-path> 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).
Stage all files:
GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git add -A
Commit:
GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git commit -m "<reason> | <timestamp> | <source-skill>" --allow-empty-message
The <reason> is a structured string (e.g., pre-design-gate, pre-wave-3, pre-qg-fix-round-2). The <source-skill> is the consuming skill name (build, quality-gate, debugging).
Record the commit hash as the checkpoint ID.
Update manifest: Append an entry to checkpoint-manifest.md in the shadow repo directory (outside the git tree):
| <hash-8-chars> | <timestamp> | <reason> | <source-skill> |
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.
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 |
Create a pre-restore safety checkpoint with reason pre-restore-safety and source checkpoint. This enables "undo the undo."
Restore:
GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git checkout <hash> -- .
Verify: Run the project's test suite or relevant subset to confirm the restored state is healthy.
Report: "Restored to checkpoint <hash> (<reason>). Safety checkpoint created at <safety-hash> — use this to undo the restore."
Create a pre-restore safety checkpoint with reason pre-restore-safety-file and source checkpoint.
Restore:
GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git checkout <hash> -- <file-path>
Report: "Restored <file-path> from checkpoint <hash> (<reason>)."
Run at session start (before first checkpoint) to reclaim space:
GIT_DIR=<shadow-path> GIT_WORK_TREE=<working-dir> git gc --prune=now
Read checkpoint-manifest.md and verify each entry's hash exists:
GIT_DIR=<shadow-path> git cat-file -t <hash>
Remove entries with invalid hashes (orphaned by prior gc).
The checkpoint manifest and shadow repo persist across compaction because they live in ~/.claude/projects/ (not in /tmp/ or in-memory).
After compaction:
~/.claude/projects/<project-hash>/checkpoints/<dir-hash>/ existscheckpoint-manifest.md to recover available checkpointsNo active marker file is needed — the shadow repo's existence IS the marker. The directory hash computation is deterministic from the working directory path.
.git directoryGIT_DIR and GIT_WORK_TREE env varsConsuming skills: