claudeers.
// Automation & Workflows

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.
// or install directly (release-binary)

Grab the latest release asset from GitHub.

# download a build from https://github.com/mishoko/claude-code-recursive-delete-guard/releases
// or clone
git clone https://github.com/mishoko/claude-code-recursive-delete-guard

// compatibility

Platformscli, api
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguagePython

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

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:

  1. copies the hook to ~/.claude/hooks/recursive_delete_guard.py,
  2. runs the self-test,
  3. backs up ~/.claude/settings.json,
  4. adds one PreToolUse entry.

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
BlockedAllowed
rm -rf $Drm -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)/xrm -rf build dist
rm -rf . / .. / ~ / / / ./* / ~/* / ~/.clauderm -rf *.diff, rm -rf */node_modules
rm -rf .git, .git/*, .[!.]*, */.git, {..,x}, a git work-tree rootrm -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 -deletefind . -name '*.pyc' -delete
ls | xargs rm -rffind . -name x -print0 | xargs -0 rm -rf
bash -c 'rm -rf $D', eval "rm -rf $D", trap 'rm -rf $T' EXITbash -c 'rm -rf -- "${D:?}"'
rsync -a --delete "$SRC/" "$DST/"rsync -a --delete src/ build/
a script (heredoc or file) containing any of thesegit 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" / $S with 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.py without raising __version__ (scripts/release_check.py bump), and the unit tests fail without a matching CHANGELOG.md section.
  • When main gets a version that has no vX.Y.Z tag yet, the release workflow 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 --version shows 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, cd into 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.
  • find and xargs fed through other filters (find … | grep … | xargs -0 rm -rf): only find and ls piped straight into xargs rm are 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 .git directory. A repository nested deeper is protected only by its own path, and a submodule or linked worktree (whose .git is a file) does not protect its parent.
  • xargs without -0. find … | xargs rm -rf blocks by design (a name with a space becomes several paths); use -print0 | xargs -0. A single-quoted trap 'rm -rf $T' EXIT blocks too: $T is 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 }]
}

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.

3 views
★ 16 stars
unclaimed
updated 15 days ago

// embed badge

claude-code-recursive-delete-guard on Claudeers
[![Claudeers](https://claudeers.com/api/badge/claude-code-recursive-delete-guard.svg)](https://claudeers.com/claude-code-recursive-delete-guard)

// retro hit counter

claude-code-recursive-delete-guard hit counter
[![Hits](https://claudeers.com/api/counter/claude-code-recursive-delete-guard.svg)](https://claudeers.com/claude-code-recursive-delete-guard)

// reviews

// guestbook

0/500

// related in Automation & Workflows

🔓

The agent that grows with you

// automationNousResearch/⟨Python⟩★ 264,763◷ MIT[ claude ]
🔓

The API to search, scrape, and interact with the web at scale. 🔥

// automationfirecrawl/⟨TypeScript⟩★ 199,533◷ AGPL-3.0[ claude ]
🔓

🌐 Make websites accessible for AI agents. Automate tasks online with ease.

// automationbrowser-use/⟨Python⟩★ 121,235◷ MIT[ claude ]
🔓

Taste-Skill - gives your AI good taste. stops the AI from generating boring, generic slop

// automationLeonxlnx/⟨JavaScript⟩★ 110,676◷ MIT[ claude ]
→ see how claude-code-recursive-delete-guard connects across the ecosystem