shellguardian

# ShellGuardian

Protect AI coding agents from deleting the wrong files before it happens.

`ShellGuardian` is a Python-first open source deletion guardrail for Codex, Claude Code, Cursor, Cursor, and other agentic workflows.

Unlike a traditional `safe-rm` wrapper, ShellGuardian focuses on prevention first:

- preview deletion risk before anything is removed
- scan the current project and suggest cleanup targets
- block obviously dangerous targets such as `src/`, `.git/`, or the workspace root
- delete only likely disposable files by default
- require confirmation for ambiguous paths
- help humans understand why something looks risky

It is designed for three reuse layers:

- Library: `safe_delete()`, `preview_delete()`, `smart_delete()`, `safe_move()`, `safe_exec()`
- CLI: `shellguardian preview|rm|move|exec`
- Future server/webhook support: policy validation and audit logging are separated from the transport layer

## Agent-ready

ShellGuardian can also be embedded into AI coding agent workflows, not just used as a standalone CLI.

- `--json` results include a `guidance` object with natural-language risk explanations and next-step suggestions
- prompt templates for Codex and Claude Code are included in [`prompts/`](./prompts/)
- the recommended interaction protocol is documented in [`docs/agent-protocol.md`](./docs/agent-protocol.md)

This makes ShellGuardian useful even for users who are not very comfortable with command-line deletion flows, because an agent can explain the risk before taking action.

## Why this exists

AI coding agents are great at automating shell tasks, but they are also very capable of deleting the wrong directory for very boring reasons:

- they misread the current path
- they confuse sibling directories
- they over-apply cleanup commands
- they treat unknown files as disposable
- they fall back to raw shell deletion when a safer API should have been used

ShellGuardian flips the default:

- reject protected paths
- keep work inside the c