🚲 backpedal

Database transactions — for your filesystem. Run any command with a safety net. If it fails, your workspace rewinds instantly. If it succeeds, you keep rolling.

Features · Quick Start · CLI · How It Works · vs Competitors

✨ Features

| Feature | What It Does | |:--------|:-------------| | 🔄 Automatic Rollback | Non-zero exit? Ctrl-C? Timeout? Everything rewinds — including untracked files | | 🪶 Zero Dependencies | No npm deps. Just Node.js + Git (or pure Merkle-tree fallback for non-git dirs) | | 📜 Full History | Every transaction logged — roll back to any snapshot by index or commit SHA | | 🤖 CI / Headless Ready | --yes flag or BACKPEDAL_AUTO_ROLLBACK=true skips TTY prompts | | ⏱️ Timeout Protection | --timeout 30000 kills hung commands and rolls back automatically | | 🛡️ Signal-Safe | Ctrl-C (SIGINT) or kill (SIGTERM) triggers rollback before exiting | | 🔀 Hybrid Backend | Prefers Git snapshots (orphaned commits, never touches your index). Falls back to SHA-256 Merkle trees |

[!NOTE] New in 1.1: Signal handling, command timeout, crypto.randomUUID() transaction IDs, private Git index isolation (never pollutes your staging area), and shell-metacharacter-safe commit messages.

🚀 Quick Start

npm install -g backpedal

# Run anything — if it breaks, you're safe
backpedal run "npm run risky-migration"

# CI mode — auto-rollback on failure, no prompts
backpedal run "make deploy" --yes --timeout 60000

📖 CLI Reference

backpedal run <command>

Wrap any shell command in a safety transaction.

backpedal run "npm test"                    # Auto-rollback if tests fail
backpedal run "npx prisma migrate dev" -y   # Skip TTY prompt
backpedal run "sleep 999" --timeout 5000    # Kill + rollback after 5s

backpedal rollback [index|sha]

Rewind to a previous transaction state.

backpedal rollback            # Undo the last transaction
backpedal rollback 1          # Undo to history index [1]
backpedal rollback abc123f    # Undo to specific commit SHA

backpedal history

List all transaction snapshots with timestamps and SHAs.

| Flag | Description | |:-----|:------------| | --yes, -y, --auto-rollback | Auto-rollback on failure (no prompt) | | --timeout <ms> | Kill command + rollback after N milliseconds | | BACKPEDAL_AUTO_ROLLBACK=true | Env var equivalent of --yes |

🔧 How It Works

┌──────────────────────────────────────────────────────┐
│  1. SNAPSHOT                                          │
│  Creates an orphaned Git commit of your entire        │
│  working tree (tracked + untracked files)              │
│  → Private GIT_INDEX_FILE — your staging area is safe │
├──────────────────────────────────────────────────────┤
│  2. EXECUTE                                           │
│  Runs your command with stdio inherited               │
│  → SIGINT/SIGTERM handlers listen for interrupts      │
├──────────────────────────────────────────────────────┤
│  3. EVALUATE                                          │
│  Exit 0 → Keep changes, log transaction               │
│  Exit ≠ 0 → git reset --hard + git clean -fd          │
│  Timeout  → SIGTERM → (5s grace) → SIGKILL → rollback │
│  Signal   → Kill child → rollback → exit              │
└──────────────────────────────────────────────────────┘

[!TIP] Not in a Git repo? backpedal falls back to SHA-256 Merkle-tree snapshots stored in .backpedal-snapshots/. Same API, no Git required.

🆚 Why backpedal?

| Tool | Paradigm | Auto-Rollback | Signal-Safe | Untracked Files | No Git Required | |:-----|:---------|:-------------:|:-----------:|:---------------:|:---------------:| | backpedal | Transaction wrapper | ✅ | ✅ | ✅ | ✅ | | SafeSandbox | Git branch snapshots | ❌ | ❌ | ❌ | ❌ | | SnapBack | Manual snapshots | ❌ | ❌ | ❌ | ✅ | | claude-oops | Claude Code only | ❌ | ❌ | ❌ | ❌ | | undoai | File-watcher daemon | ❌ | ❌ | ✅ | ✅ |

The difference: Every other tool is a snapshot tool — you take a picture, then later decide to restore it. backpedal is a transaction wrapper — you run a command, and the rollback decision is automatic. No separate snapshot step. No manual restore. Just run your command and forget about it.

See the competitive analysis for details.

📄 License

MIT · codecrypt112