A deletion guardrail for Codex, Claude Code, Cursor, and other AI coding agents.

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/
• the recommended interaction protocol is documented in 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