safe-rm

# Safe Delete Protection for Claude Code

> **Catch 99% of accidental deletions with one simple install.**

Stop AI agents from accidentally deleting `.env` files, git-tracked code, or critical system files. This plugin adds automatic safety checks to every `rm` command in Claude Code sessions.

**Zero configuration. Zero learning curve. Just install and forget.**

## The Problem

AI agents are powerful, but they can make costly mistakes:

```bash
# Claude executes: rm .env
# 💥 Your API keys are gone

# Claude executes: rm -rf ../important-project
# 💥 Wrong directory deleted

# Claude executes: rm src/config.ts
# 💥 Git-tracked file removed without confirmation
```

**One accidental deletion can cost hours of recovery work.**

## The Solution

A lightweight safety layer you can **"just install and forget"**:
- ✅ 30-second setup, zero configuration
- ✅ Works transparently (no new commands to learn)
- ✅ Catches most common AI deletion mistakes
- ✅ Zero performance impact, minimal false positives

## Why This Plugin, Not Other Solutions?

You might be using these common approaches to protect your files:

### ❌ Approach 1: Deny `rm` in settings.json

```json
{
  "permissions": {
    "deny": ["Bash(rm *)"]
  }
}
```

**Problem:** Pattern matching is fragile and can be bypassed:
- `rm file.txt` → ❌ Blocked
- `rm  file.txt` (extra space) → ✅ Bypassed
- `/bin/rm file.txt` → ✅ Bypassed
- Known bug: [deny permissions not enforced](https://github.com/anthropics/claude-code/issues/6699)

### ❌ Approach 2: Instructions in CLAUDE.md

```markdown
IMPORTANT: Never use the rm command to delete files.
```

**Problem:** LLM instructions are unreliable:
- Claude may ignore instructions under certain contexts
- No guaranteed enforcement
- [Real incidents](https://github.com/anthropics/claude-code/issues/12489): "rm -rf executed on home directory despite explicit instructions"

### ✅ This Plugin: Shell-Layer Protection

This plugin works at the **shell execution layer** — below the LLM:

```
User Request → Claude (LLM) → Shell Command → [🛡️ THIS PLUGIN] → System
```

**Why it works reliably:**
1. **Physical layer enforcement** — runs BEFORE the system executes `rm`
2. **Catches all `rm` variants** — direct interception, not pattern matching
3. **LLM-agnostic** — works regardless of what Claude decides
4. **Zero regex fragility** — no bypass through spacing or syntax tricks
5. **AI-friendly feedback** — clear error messages guide the agent to correct actions

**Note:** This doesn't protect against other deletion methods (like `find -delete`), but it handles 99% of accidental AI deletions with zero productivity cost.

## Quick Start

### Installation

```bash
# Add the marketplace
/plugin marketplace add TeXmeijin/safe-rm-claude-plugin

# Install the plugin
/plugin install safe-rm@safe-rm-marketplace
```

**That's it!** Your Claude Code sessions now catch most accidental deletions automatically.

## How It Works

After installation, all `rm` commands in Claude Code are transparently protected:

```bash
# You use rm normally
rm .env

# But the plugin automatically blocks dangerous operations
# ❌ FORBIDDEN: You are trying to remove dotfile: .env
# You must ask your leader to run manually: rm /path/to/.env
```

**You don't need to learn new commands or change your workflow.** The protection works invisibly in the background.

### Smart AI Guidance

Unlike silent blocking, this plugin provides **actionable feedback** that helps Claude understand what went wrong and what to do next:

```bash
rm -r large-directory/  # contains 50+ files

# ❌ Error output:
# FORBIDDEN: Directory contains 50 files (limit: 10)
# Directory: /Users/you/project/large-directory
# NEXT ACTION👉: You MUST ask your manager to run manually: rm -rf /path/to/directory
```

**This prevents AI runaway behavior:**
- ✅ Claude sees exactly why the operation was blocked
- ✅ Claude learns what alternative actions to suggest
- ✅ Claude stops trying dangerous variations
- ✅ Claude can ask the user for confirmation instead

## What's Protected

The plugin enforces 6 critical safety checks:

| Protection | What It Does |
|------------|--------------|
| 🔒 **Dotfiles** | Blocks deletion of configuration files (`.env`, `.gitignore`, etc.) |
| 🔒 **Git-managed files** | Requires confirmation before removing tracked files |
| 🔒 **Outside project scope** | Prevents deleting files outside your current directory |
| 🔒 **System directories** | Blocks removal of `/`, `~`, and other critical paths |
| 🔒 **Gitignored files** | Protects important files like `node_modules`, build outputs |
| 🔒 **Large directories** | Limits recursive deletion to 10 files (configurable) |

## Examples

### Protected Scenarios

```bash
# ❌ Blocked: Dotfile
rm .env
# FORBIDDEN: You are trying to remove dotfile: .env
# You must ask your leader to run manually: rm /path/to/.env
# → Claude learns: "I should ask the user for permission"

# ❌ Blocked: Outside current directory
rm ../important-file
# FORBIDDEN: Cannot remove files outside current directory
# Current directory: /Users/you/project
# Target file: /Users/you/important-file
# You can override with --forbidden-outside-cwd false option
# → Claude learns: "This file is outside the project scope"

# ❌ Blocked: System directory
rm -rf /
# FORBIDDEN: Cannot remove special directory: /
# You must manually run: rm /
# → Claude learns: "This is a critical system path"

# ❌ Blocked: Too many files
rm -r large-directory/  # contains 50+ files
# FORBIDDEN: Directory contains 50 files (limit: 10)
# NEXT ACTION👉: You MUST ask your manager to run manually
# → Claude learns: "I should suggest alternative approaches"
```

### Safe Operations

```bash
# ✅ Allowed: Regular file in current directory
rm temp-file.txt

# ✅ Allowed: Small directory
rm -r test-folder/  # contains 5 files

# ✅ Allowed: With explicit override
rm --forbidden-dotfiles false .temporary-cache
```

## Advanced Configuration

Most users won't need to change anything, but you can customize protection rules when needed:

```bash
# Temporarily allow dotfile removal
rm --forbidden-dotfiles false .temporary-cache

# Increase file count limit for large directories
rm --forbidden-file-count 50 build-output/

# Allow deletion outside current directory (use with caution!)
rm --forbidden-outside-cwd false /path/to/file
```

### All Available Options

| Option | Default | Override Example |
|--------|---------|------------------|
| `--forbidden-dotfiles` | `true` | `rm --forbidden-dotfiles false .env` |
| `--forbidden-outside-cwd` | `true` | `rm --forbidden-outside-cwd false ../file` |
| `--forbidden-file-count` | `10` | `rm --forbidden-file-count 50 dir/` |
| `--forbidden-special-dirs` | `true` | Cannot be overridden |
| `--forbidden-gitignored` | `true` | `rm --forbidden-gitignored false node_modules/` |
| `--only-git-new-file` | `false` | `rm --only-git-new-file true newfile.txt` |

## Technical Details

The plugin works by installing a SessionStart hook that creates a transparent alias: `rm` → `safe-rm`.

When Claude runs `rm`, it actually executes the protection script which:
1. Validates the operation against all safety rules
2. If safe, calls the system's `/bin/rm`
3. If unsafe, blocks the operation with a clear error message

**This happens automatically — no manual configuration required.**

## Design Philosophy

> **"Better to have it than not" — Simple protection that works 99% of the time without slowing you down.**

This plugin doesn't claim to be a perfect security solution. There are other ways to delete files (e.g., `find -delete`, direct system calls), and determined attempts can bypass it.

**But that's not the point.**

The goal is to catch **common accidental deletions** with **minimal friction**:
- ✅ Simple, focused on `rm` command only
- ✅ Covers 99% of real-world AI deletion mistakes
- ✅ Zero impact on productivity
- ✅ Install once, forget about it

**Think of it as a seatbelt** — not bulletproof armor. It won't save you from every possible accident, but it dramatically reduces the most common risks with almost no effort.

For advanced users who need more comprehensive protection, this plugin can be extended with custom rules. But for most developers, **this "just enough" protection is exactly what you need.**

## For Developers

### Local Testing

```bash
# Test without installing
claude --plugin-dir ~/path/to/safe-rm-claude-plugin

# Or install locally
/plugin marketplace add ~/path/to/safe-rm-claude-plugin
/plugin install safe-rm@safe-rm-marketplace
```

### Project Structure

```
.claude-plugin/      # Plugin configuration
├── plugin.json      # Metadata
└── marketplace.json # Marketplace definition
hooks/hooks.json     # Auto-setup on session start
bin/safe-rm          # Protection script
```

## License & Contributing

MIT License • Contributions welcome!

Created by [meijin](https://github.com/TeXmeijin)