Work safely with agents like Claude Code, Cursor, Kiro CLI.

AI coding agents are powerful, but with great power comes rm -rf /.

I've been recommending tools like Claude Code and Cursor to junior devs and non-technical folks lately. These agents can execute shell commands autonomously, which is useful. But it also means a single hallucination could wipe their SSH keys, nuke a folder, or brick a meticulously created dev environment.

Frontier models do come with guardrails, but I wanted control over project-specific no-nos too - like pushing to master or running that one script that drops the staging database.

An LLM deciding whether a command is "safe" is probabilistic. I wanted something classical: a system where I define exactly what's allowed and what's blocked, with no ambiguity.

Inspired by .gitignore: simple pattern matching, one rule per line, easy for anyone to read and modify.

Built with Kiro for the Kiroween Hackathon 2025

• Deterministic rules, not probabilistic LLM guardrails
• .gitignore-style syntax anyone can read
• Recursive command unwrapping (catches sudo bash -c "rm -rf /")
• Catastrophic path detection (blocks rm -rf /, rm -rf ~, etc.)
• Zero latency - all validation is local

npm install -g ai-agentguard

Or from source:

git clone https://github.com/krishkumar/agentguard
cd agentguard
npm install && npm run build
npm link

agentguard init           # Creates .agentguard with sensible defaults
agentguard install claude # Registers the Claude Code hook
agentguard install cursor # Registers the Cursor hook
agentguard install kiro   # Registers the Kiro CLI hook

That's it. Every shell command Claude tries to run now goes through AgentGuard first.

AgentGuard intercepts shell commands before they execute and validates them against a simple rules file. If a command matches a block pattern, it gets stopped. If it's allowed, it runs normally.

AgentGuard doesn't just look at the surface command - it recursively unwraps nested command wrappers to find what's actually being executed. This catches attempts to hide dangerous commands behind innocent-looking wrappers:

# All of these get unwrapped to detect the underlying "rm" command:
sudo rm -rf /                    # → rm -rf /
bash -c "rm -rf /"               # → rm -rf /
sudo env PATH=/bin bash -c "rm -rf /"  # → rm -rf /
find / -exec rm -rf {} \;        # → rm (with dynamic args)
xargs rm -rf                     # → rm (with dynamic args)

Supported wrappers:

• Passthrough: sudo, doas, env, nice, nohup, timeout, time, watch, strace, ltrace, ionice, chroot, runuser, su
• Shell -c: bash, sh, zsh, dash, fish, ksh, csh, tcsh
• Dynamic executors: xargs, parallel, find -exec, find -delete

Here's what a standard block looks like in practice:

> run nuketown.sh

⏺ Bash(./nuketown.sh)
  ⎿  Error: PreToolUse:Bash hook error: [node ./dist/bin/claude-hook.js]: 🚫
     AgentGuard BLOCKED: ./nuketown.sh
     Rule: *nuketown*
     Reason: Blocked by rule: *nuketown*

The agent tried to run the command. AgentGuard caught it. Nothing bad happened.

You create a .agentguard file in your project root with patterns for commands you want to block:

# The obvious dangerous stuff
!rm -rf /
!rm -rf /*
!rm -rf ~
!rm -rf ~/*
!mkfs*
!dd if=* of=/dev/*
!shred*

# Don't let agents read my secrets
!cat ~/.ssh/*
!cat ~/.aws/*
!cat */.env

# Block that sketchy script I use for demos
!*nuketown*

The syntax is deliberately simple. ! means block, * is a wildcard. That's basically it.

Claude Code has a hook system that lets you intercept tool calls before they run. AgentGuard registers a PreToolUse hook that receives every Bash command as JSON, validates it against your rules, and returns exit code 0 (allow) or 2 (block).

Cursor also supports the same PreToolUse hook system as Claude Code. AgentGuard registers a hook that intercepts Bash commands, validates them against your rules, and returns the appropriate exit code to allow or block execution.

Kiro CLI also supports hooks through its agent configuration system. AgentGuard registers a PreToolUse hook that intercepts execute_bash commands, validates them against your rules, and returns the appropriate exit code.

agentguard init             # Create .agentguard with sensible defaults
agentguard install claude   # Register the Claude Code hook
agentguard install cursor   # Register the Cursor hook
agentguard install kiro     # Register the Kiro CLI hook
agentguard uninstall claude # Remove the Claude Code hook
agentguard uninstall cursor # Remove the Cursor hook
agentguard uninstall kiro   # Remove the Kiro CLI hook
agentguard check "rm -rf /" # Test if a command would be blocked

AgentGuard now supports Claude Code, Cursor, and Kiro CLI through their respective hook systems. Future integrations planned:

• Windsurf
• Other agentic tools as they add hook APIs

The core validation logic is agent-agnostic, so adding new integrations is mostly about figuring out each tool's interception mechanism.

AgentGuard is defense-in-depth, not a complete sandbox.

• Blocks dangerous shell commands before execution
• Scans for catastrophic paths (/, ~, /home) anywhere in arguments
• Unwraps wrapper commands (sudo, bash -c) to find the real command
• Analyzes script contents before execution (Python, Node, Shell)
• Provides project-specific rules versioned with your code

• Full sandboxing - Use Docker/containers for true isolation
• Binary inspection - Cannot analyze compiled executables
• Network blocking - Does not prevent data exfiltration
• Complete bypass prevention - A determined attacker can work around pattern matching

Many developers run AI agents with --dangerously-skip-permissions or habitually auto-accept prompts. AgentGuard catches the common footguns - accidental rm -rf /, leaked credentials, that one script that drops staging - even when permission prompts are bypassed.

For critical systems, combine AgentGuard with containerization. This tool handles the everyday "oh no what did it just run" moments; Docker handles the adversarial edge cases.

• Claude Code: Hooks Documentation
• Cursor: Agent Hooks Documentation
• Kiro CLI: Hooks Documentation

This project was built using Kiro for the Kiroween Hackathon. The rule engine, CLI, and Claude Code integration were all developed with Kiro's assistance.

MIT License