
claude-code-recursive-delete-guard
Claude Code hook that blocks unquoted rm -rf $VAR and repo-root deletes, even in bypassPermissions mode
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up claude-code-recursive-delete-guard (release-binary project) into my current project. Found on https://claudeers.com/claude-code-recursive-delete-guard Repo: https://github.com/mishoko/claude-code-recursive-delete-guard Homepage/docs: — Detected install method: release-binary → inspect the README Category: automation. Platforms: cli, api. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: unknown; community-verified: false. Confirm the source before running anything.
Grab the latest release asset from GitHub.
# download a build from https://github.com/mishoko/claude-code-recursive-delete-guard/releases
git clone https://github.com/mishoko/claude-code-recursive-delete-guard
// compatibility
| Platforms | cli, api |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Python |
claude-code-recursive-delete-guard
A Claude Code PreToolUse hook that blocks unsafe recursive deletes before they run, in every permission mode, bypassPermissions included.
One Python file. Standard library only. About 40 ms per tool call, nearly all of it Python start-up (the check itself takes well under 1 ms for a typical command). macOS and Linux; Windows is not supported.
Install
curl -fsSL https://github.com/mishoko/claude-code-recursive-delete-guard/releases/latest/download/recursive_delete_guard.py -o /tmp/rdg.py \
&& python3 /tmp/rdg.py --install
--install does four things:
- copies the hook to
~/.claude/hooks/recursive_delete_guard.py, - runs the self-test,
- backs up
~/.claude/settings.json, - adds one
PreToolUseentry.
Running it again changes nothing, and existing hooks are kept. An older entry is upgraded in place: its matcher gains the tools it lacks (Monitor) and its command is updated. Restart open Claude Code sessions afterwards.
To check that it's live, ask Claude to run true || rm -rf /tmp/probe-$$. The rm can never execute, and you should see Blocked by recursive_delete_guard.
What it blocks
tool call (Bash / Monitor / Write / Edit / MultiEdit)
│
▼
┌─────────────────────────────────────────┐
│ rm -r with an unquoted $VAR / $(…)? │──► block
│ a quoted "$VAR" whose empty or known │
│ value is a protected path? │──► block
│ target (or a glob match) is / · ~ · │
│ cwd · a parent · a git work-tree root │
│ · .git or inside · ~/.claude · ~/.ssh?│──► block
│ find -delete with no name test, │
│ xargs rm -r without -0, │
│ rsync --delete into one of those? │──► block
│ writes, runs or re-parses a script │
│ that does any of the above? │──► block
└─────────────────┬───────────────────────┘
│ otherwise
▼
runs
| Blocked | Allowed |
|---|---|
rm -rf $D | rm -rf -- "${D:?}" |
rm -rf "$D"/* (an unknown D is empty: that is /*) | rm -rf -- "${D:?}"/* |
rm -rf "$HOME", D=/; rm -rf "$D", rm -rf "${D:-.}" | rm -rf "$HOME/.cache/x", D=build; rm -rf "$D" |
rm -r -f $(dirname $R)/x | rm -rf build dist |
rm -rf . / .. / ~ / / / ./* / ~/* / ~/.claude | rm -rf *.diff, rm -rf */node_modules |
rm -rf .git, .git/*, .[!.]*, */.git, {..,x}, a git work-tree root | rm -rf output/run, rm -rf {build,dist} |
cd .. && rm -rf repo, cd build; rm -rf * (the cd may fail) | cd build && rm -rf * |
find . -delete, find . -type f -delete, find $T -type f -delete | find . -name '*.pyc' -delete |
ls | xargs rm -rf | find . -name x -print0 | xargs -0 rm -rf |
bash -c 'rm -rf $D', eval "rm -rf $D", trap 'rm -rf $T' EXIT | bash -c 'rm -rf -- "${D:?}"' |
rsync -a --delete "$SRC/" "$DST/" | rsync -a --delete src/ build/ |
| a script (heredoc or file) containing any of these | git rm -r --cached x, echo "rm -rf $x" |
Where it looks:
- the Bash (and Monitor) command as a whole: quotes and heredocs that span lines,
\-newline continuations, redirections (2>/dev/null rm …), commands inside$(...), backticks, loops, functions and&&/;/|chains, and behind wrappers (sudo -u x,timeout -s KILL 60,env -u X,nohup,xargs,caffeinate, …), - strings the shell parses again:
bash -c,sh -c,eval,trap,env -S,su -c,watch, a here-string or a heredoc fed to a shell,echo … | sh, and the$(…)of an unquoted heredoc, - heredoc bodies that are shell scripts (shell shebang, a
.sh-type target, fed to a shell, or written to a file the same command runs later); a commit message or a Python heredoc is treated as data, - shell scripts the command runs:
./x.sh,bash x,source x,"$S"/$Swith S assigned earlier, up to 8 levels deep, - shell files written or edited with Write / Edit / MultiEdit, judged on the file the edit produces; only the issues the edit adds are reported.
The working directory follows cd, pushd and env -C. A ( … ) subshell restores it, and after ; both the old
and the new directory count, because the cd may have failed. cd x || exit and if cd x; then count as certain.
On a block the hook exits with code 2, and Claude Code shows Claude the reason. Claude can then rewrite the command with a quoted, guarded path:
rm -rf -- "${D:?}" # one operand; fails if D is empty or unset
Why unquoted operands
An unquoted operand is split and globbed by the shell. If its value is empty, or contains a space, rm -rf receives different paths than intended. Shells also disagree about this. zsh, the default login shell on macOS and the shell the Bash tool runs there, does not split set -- $var. bash does split an unquoted $D. A value built in one shell and expanded in the other can turn into several paths:
zsh: set -- "main <repo> main" → $1 = "main <repo> main" (one word)
bash: rm -rf $D → rm -rf <out>/main <repo> main
▲
the repository root
A permission rule only sees the top-level command (./helper.sh ...), not the rm inside the script, which is why the hook also reads scripts.
Testing
python3 -m unittest # the full case table (tests/cases.py)
python3 recursive_delete_guard.py --self-test # the installer's built-in check
tests/cases.py is a table of commands with the expected verdict (BLOCK or PASS). The tests only hand strings to the
guard; they never run the commands. A row marked gap= is a known gap: the test asserts the guard still gets it
wrong, so it turns red the moment someone fixes it. FP_CORPUS lists everyday commands that must never be blocked.
The rows marked P1- and P2- come from the two rounds of the 1.2.0 review panel; tests/test_guard.py also checks the hook's I/O contract,
the installer's settings update, random input, and time limits.
CI runs both on Ubuntu (system Python and 3.8) and on macOS (/usr/bin/python3).
Releasing
The version lives in one place, __version__ in recursive_delete_guard.py. The rest is automatic:
- CI fails when a push or pull request changes
recursive_delete_guard.pywithout raising__version__(scripts/release_check.py bump), and the unit tests fail without a matchingCHANGELOG.mdsection. - When
maingets a version that has novX.Y.Ztag yet, thereleaseworkflow runs the tests, then tags the commit and publishes a GitHub release: its notes are that CHANGELOG section, its asset is the guard. The install command above downloads the latest release. - An installed hook never updates itself (a delete guard should not fetch code on its own). Run the install command
again to update;
python3 ~/.claude/hooks/recursive_delete_guard.py --versionshows what you have.
Pick the number by the policy at the top of CHANGELOG.md (PATCH, MINOR, MAJOR). To check before pushing:
python3 scripts/release_check.py bump origin/main.
What it does NOT catch
What remains after the 1.2.0 review (no row in tests/cases.py is marked gap= today):
- Other platforms and agents. Windows (cmd.exe, PowerShell
Remove-Item -Recurse,C:\paths) and the Codex CLI (apply_patch, its own hook format) are not supported. Claude Code on macOS and Linux is. - Values the shell only knows at run time. A command built from a variable whose value is not visible in the same
command (
bash -c "$CMD",$R -rf,${RM:-rm}), functions and aliases defined in an earlier call,cdinto a directory computed by an unknown program, and loops over the output of a program (for d in $(ls)). - Deletes by other programs:
python -c 'shutil.rmtree(…)',node,perl,make clean,npm run clean,docker exec … rm,ssh host rm …,git clean -fdx,git reset --hard. findandxargsfed through other filters (find … | grep … | xargs -0 rm -rf): onlyfindandlspiped straight intoxargs rmare judged by what they print.- Names more than one level down. A directory is protected when it is a git work tree, or when a directory
directly inside it has a
.gitdirectory. A repository nested deeper is protected only by its own path, and a submodule or linked worktree (whose.gitis a file) does not protect its parent. xargswithout-0.find … | xargs rm -rfblocks by design (a name with a space becomes several paths); use-print0 | xargs -0. A single-quotedtrap 'rm -rf $T' EXITblocks too:$Tis unquoted when it runs.- Limits. Scripts and re-parsed strings are followed 8 levels deep (deeper blocks); a glob is expanded up to 20,000 directory entries; a word with more than 256 possible values blocks; checking stops after 5 s (and blocks).
- A path swapped between the check and the run, and deleting a protected path on purpose (a throwaway clone with
.git: run that one yourself).
Git's own temporary state inside .git (rebase-merge, rebase-apply, sequencer, worktrees/<name>) can be
deleted; everything else inside .git is protected as history.
It doesn't replace backups: keep an off-machine copy of your repositories (git bundle create … --all, a push).
Manual install
mkdir -p ~/.claude/hooks
curl -fsSL https://github.com/mishoko/claude-code-recursive-delete-guard/releases/latest/download/recursive_delete_guard.py \
-o ~/.claude/hooks/recursive_delete_guard.py
python3 ~/.claude/hooks/recursive_delete_guard.py --self-test
Add under "hooks" → "PreToolUse" in ~/.claude/settings.json:
{
"matcher": "Bash|Monitor|Write|Edit|MultiEdit",
"hooks": [{ "type": "command", "command": "python3 -I \"$HOME/.claude/hooks/recursive_delete_guard.py\"", "timeout": 10 }]
}
Related
The 1.2.0 work follows the review by @_shift_MIND on X, who ran this guard through Claude and Codex round after round and listed every gap they found.
Upstream report: anthropics/claude-code#107271. Same failure class: #102901, #95426, #103027, #91498.
License
MIT
// faq
What is claude-code-recursive-delete-guard?
Claude Code hook that blocks unquoted rm -rf $VAR and repo-root deletes, even in bypassPermissions mode. It is open-source on GitHub.
Is claude-code-recursive-delete-guard free to use?
claude-code-recursive-delete-guard is open-source under the MIT license, so it is free to use.
What category does claude-code-recursive-delete-guard belong to?
claude-code-recursive-delete-guard is listed under automation in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/claude-code-recursive-delete-guard)
// retro hit counter
[](https://claudeers.com/claude-code-recursive-delete-guard)
// reviews
// guestbook
// related in Automation & Workflows
The API to search, scrape, and interact with the web at scale. 🔥
🌐 Make websites accessible for AI agents. Automate tasks online with ease.
Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop