recover 🛟

Undo the destructive commands your AI coding agent runs that /rewind can't.

Claude Code's native /rewind is great — it undoes the file edits the model makes through its editing tools. But it has a documented blind spot, straight from the docs:

Bash command changes not tracked. Checkpointing does not track files modified by bash commands. For example, if Claude Code runs rm file.txt, mv old.txt new.txt, or cp source.txt dest.txt... these file modifications cannot be undone through rewind.

So the moment your agent runs rm -rf, a bad mv, a clobbering > redirect, or a DROP TABLE, you're on your own. recover is the safety net for exactly that.

$ rm -rf src/          # your agent does something terrifying

$ recover undo         # you bring it back
✓ Restored 1 path(s) from 2026-06-04T...:
  ← /Users/you/project/src

How it works

recover registers as a Claude Code PreToolUse hook on the Bash tool. Before any bash command runs, it:

1. Detects destructive operations — rm, mv, cp overwrites, truncating > redirects, truncate, and risky DB writes (DROP/DELETE/TRUNCATE/UPDATE).
2. Snapshots the exact files/dirs about to be lost into a local store (in your home dir, not the project — see Where snapshots live).
3. Lets the command run — it never blocks your agent. It's a safety net, not a gate.

Then recover undo restores the last snapshot. It complements /rewind rather than replacing it: /rewind for edits, recover for destruction.

It's deliberately small, has zero network access, and stores everything locally so you can inspect exactly what it does.

Install

Fastest — no global install:

npx @vulcnize/recover@latest install     # hook + /recover command + skill in ./.claude/

Or globally:

npm install -g @vulcnize/recover
recover install                    # add --global to set it up in ~/.claude/

Or as a Claude Code plugin (bundles the hook, command, and skill):

/plugin marketplace add vulcnize/recover
/plugin install recover@recover

The plugin still needs the recover binary on your PATH (npm i -g @vulcnize/recover), since the hook runs recover hook.

Cross-agent (Cursor, Codex, …) — the skill only:

npx skills add vulcnize/recover --skill recover

This installs the recover skill so the agent knows to use recover. The automatic snapshot hook is Claude Code–specific — on other agents, use recover guard '<cmd>' or that agent's own pre-command hook.

Every path gives you: the protective hook, a /recover slash command, and a skill to drive it from inside Claude (below). Snapshots live in your home dir, so nothing is added to your project — no .recover/ folder, no .gitignore changes.

Drive it from Claude (like /rewind)

No need to switch to a terminal — recover install adds a slash command and a skill:

/recover undo          ← restore the most recent snapshot
/recover list          ← see what's recoverable
/recover check 'rm -rf build'

Or just say it in plain language — the skill picks it up:

"undo that delete" · "get those files back" · "what did you just remove?"

Claude will run the right recover command and report what was restored.

Usage

recover list            # snapshots taken before destructive commands
recover list --all      # snapshots across every project
recover undo            # restore the most recent snapshot
recover undo <id>       # restore a specific snapshot
recover where           # show where this project's snapshots are stored
recover guard '<cmd>'   # snapshot, THEN run a command — a manual safety net for humans
recover check '<cmd>'   # dry-run: what would recover snapshot for this command?
recover uninstall       # remove the hook

Use guard to wrap anything risky yourself, agent or not:

$ recover guard 'rm -rf build'
recover: snapshotted 1 path(s) — `recover undo` to restore
$ recover undo
✓ Restored 1 path(s)...

And check shows how the detector reasons about a command:

$ recover check 'rm -rf build && psql -c "DROP TABLE users"'

  recover would act on this command:

  [snapshot] rm — rm -rf build
     • /Users/you/project/build
  [flag (no auto-undo)] db — psql -c DROP TABLE users
     Destructive database write detected. recover flags it but cannot auto-restore DB state in v0.1.

What's covered

| Operation | v0.1 | |---|---| | rm (files & dirs) | ✅ snapshot + undo | | mv (source loss / dest overwrite) | ✅ snapshot + undo | | cp (dest overwrite) | ✅ snapshot + undo | | Truncating > redirect, truncate | ✅ snapshot + undo | | git reset --hard, clean -f, checkout -f | ⚠️ flagged (use git reflog) | | Destructive SQL via psql/mysql/sqlite3 | ⚠️ flagged (DB undo coming in v0.2) |

Limitations (the honest ones)

• It snapshots before the command, so it only protects paths that existed at that moment.
• Bash is a big language; detection covers the common destructive shapes, not every exotic one. recover check shows you exactly what it sees.
• DB and git discards are flagged, not auto-undone in v0.1 — restoring those is on the roadmap.
• Snapshots are capped at 50 / 500 MB per project (oldest pruned automatically).

Where snapshots live

To keep your projects clean, snapshots are stored in the per-OS app-state directory, not in the project (no .recover/ folder, no .gitignore edits):

| OS | Location | |---|---| | Linux | $XDG_STATE_HOME/recover → ~/.local/state/recover | | macOS | ~/Library/Application Support/recover | | Windows | %LOCALAPPDATA%\recover |

They're keyed by project root (nearest .git ancestor, else the directory), so recover undo / /recover undo work from anywhere in the project. Set RECOVER_STORE_DIR to override the location.

recover where        # show this project's store path
recover list --all   # snapshots across every project

Roadmap

• recover undo for database writes (transaction wrapping / pre-write dumps)
• Configurable "ask before running" guard mode for the truly destructive ops
• tree-sitter-bash detection for fuller bash coverage
• Pluggable storage backends — git / hardlink dedup for large repos (the engine is already backend-agnostic)

Development

npm install
npm test          # vitest — detection + end-to-end roundtrip
npm run build     # tsc → dist/
npm run lint      # biome

Regenerate the demo GIF with VHS:

npm i -g @vulcnize/recover   # so `recover` is on PATH
vhs demo.tape          # → demo.gif

License

MIT