{"id":35795637,"url":"https://github.com/krishkumar/agentguard","last_synced_at":"2026-01-20T17:03:38.595Z","repository":{"id":327777066,"uuid":"1110747989","full_name":"krishkumar/agentguard","owner":"krishkumar","description":"Work safely with AI agents like Claude Code, Cursor, Kiro","archived":false,"fork":false,"pushed_at":"2025-12-17T03:29:30.000Z","size":239,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-20T12:45:58.694Z","etag":null,"topics":["agents","ai-safety","claude","cli","developer-tools","kiro","kiro-cli","kiroween","security"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/krishkumar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-05T16:55:23.000Z","updated_at":"2025-12-17T03:28:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/krishkumar/agentguard","commit_stats":null,"previous_names":["krishkumar/agentguard"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/krishkumar/agentguard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krishkumar%2Fagentguard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krishkumar%2Fagentguard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krishkumar%2Fagentguard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krishkumar%2Fagentguard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krishkumar","download_url":"https://codeload.github.com/krishkumar/agentguard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krishkumar%2Fagentguard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai-safety","claude","cli","developer-tools","kiro","kiro-cli","kiroween","security"],"created_at":"2026-01-07T09:58:14.867Z","updated_at":"2026-01-20T17:03:38.581Z","avatar_url":"https://github.com/krishkumar.png","language":"TypeScript","readme":"# AgentGuard\n\n[![CI](https://github.com/krishkumar/agentguard/workflows/CI/badge.svg)](https://github.com/krishkumar/agentguard/actions)\n[![npm version](https://badge.fury.io/js/ai-agentguard.svg)](https://www.npmjs.com/package/ai-agentguard)\n[![npm downloads](https://img.shields.io/npm/dm/ai-agentguard.svg)](https://www.npmjs.com/package/ai-agentguard)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/ai-agentguard.svg)](https://nodejs.org/)\n\n**Work safely with agents like Claude Code, Cursor, Kiro CLI.**\n\nAI coding agents are powerful, but with great power comes `rm -rf /`.\n\nI'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.\n\nFrontier 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.\n\nAn 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. \n\nInspired by `.gitignore`: simple pattern matching, one rule per line, easy for anyone to read and modify.\n\n\u003e Built with [Kiro](https://kiro.dev) for the Kiroween Hackathon 2025\n\n## Highlights\n\n- Deterministic rules, not probabilistic LLM guardrails\n- `.gitignore`-style syntax anyone can read\n- Recursive command unwrapping (catches `sudo bash -c \"rm -rf /\"`)\n- Catastrophic path detection (blocks `rm -rf /`, `rm -rf ~`, etc.)\n- Zero latency - all validation is local\n\n### Supported Agents\n\n| Agent | Status | Install Command |\n|-------|--------|-----------------|\n| Claude Code | ✅ Supported | `agentguard install claude` |\n| Cursor | ✅ Supported | `agentguard install cursor` |\n| Kiro CLI | ✅ Supported | `agentguard install kiro` |\n| OpenCode | ✅ Supported | `agentguard install opencode` |\n| Windsurf | 🔜 Coming soon | - |\n\n## Install\n\n```bash\nnpm install -g ai-agentguard\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/krishkumar/agentguard\ncd agentguard\nnpm install \u0026\u0026 npm run build\nnpm link\n```\n\n## Quick Start\n\n```bash\nagentguard init           # Creates .agentguard with sensible defaults\nagentguard install claude # Registers the Claude Code hook\nagentguard install cursor # Registers the Cursor hook\nagentguard install kiro   # Registers the Kiro CLI hook\nagentguard install opencode # Registers the OpenCode plugin\n```\n\nThat's it. Every shell command Claude tries to run now goes through AgentGuard first.\n\n## What it does\n\nAgentGuard 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.\n\n### Recursive Command Unwrapping\n\nAgentGuard 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:\n\n```bash\n# All of these get unwrapped to detect the underlying \"rm\" command:\nsudo rm -rf /                    # → rm -rf /\nbash -c \"rm -rf /\"               # → rm -rf /\nsudo env PATH=/bin bash -c \"rm -rf /\"  # → rm -rf /\nfind / -exec rm -rf {} \\;        # → rm (with dynamic args)\nxargs rm -rf                     # → rm (with dynamic args)\n```\n\n**Supported wrappers:**\n- **Passthrough**: `sudo`, `doas`, `env`, `nice`, `nohup`, `timeout`, `time`, `watch`, `strace`, `ltrace`, `ionice`, `chroot`, `runuser`, `su`\n- **Shell -c**: `bash`, `sh`, `zsh`, `dash`, `fish`, `ksh`, `csh`, `tcsh`\n- **Dynamic executors**: `xargs`, `parallel`, `find -exec`, `find -delete`\n\nHere's what a standard block looks like in practice:\n\n```\n\u003e run nuketown.sh\n\n⏺ Bash(./nuketown.sh)\n  ⎿  Error: PreToolUse:Bash hook error: [node ./dist/bin/claude-hook.js]: 🚫\n     AgentGuard BLOCKED: ./nuketown.sh\n     Rule: *nuketown*\n     Reason: Blocked by rule: *nuketown*\n```\n\nThe agent tried to run the command. AgentGuard caught it. Nothing bad happened.\n\n## The rules file\n\nYou create a `.agentguard` file in your project root with patterns for commands you want to block:\n\n```bash\n# The obvious dangerous stuff\n!rm -rf /\n!rm -rf /*\n!rm -rf ~\n!rm -rf ~/*\n!mkfs*\n!dd if=* of=/dev/*\n!shred*\n\n# Don't let agents read my secrets\n!cat ~/.ssh/*\n!cat ~/.aws/*\n!cat */.env\n\n# Block that sketchy script I use for demos\n!*nuketown*\n```\n\nThe syntax is deliberately simple. `!` means block, `*` is a wildcard. That's basically it.\n\n## How it works with AI Agents\n\n### Claude Code\n\nClaude 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).\n\n### Cursor\n\nCursor 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.\n\n### Kiro CLI\n\nKiro 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.\n\n### OpenCode\n\nOpenCode supports plugins through its plugin system. AgentGuard creates a plugin that uses the `tool.execute.before` hook to intercept bash commands, validates them against your rules, and throws an error to block execution if needed.\n\n## Commands\n\n```bash\nagentguard init             # Create .agentguard with sensible defaults\nagentguard install claude   # Register the Claude Code hook\nagentguard install cursor   # Register the Cursor hook\nagentguard install kiro     # Register the Kiro CLI hook\nagentguard install opencode # Register the OpenCode plugin\nagentguard uninstall claude # Remove the Claude Code hook\nagentguard uninstall cursor # Remove the Cursor hook\nagentguard uninstall kiro   # Remove the Kiro CLI hook\nagentguard uninstall opencode # Remove the OpenCode plugin\nagentguard check \"rm -rf /\" # Test if a command would be blocked\n```\n\n## Roadmap\n\nAgentGuard now supports Claude Code, Cursor, and Kiro CLI through their respective hook systems. Future integrations planned:\n\n- Windsurf\n- Other agentic tools as they add hook APIs\n\nThe core validation logic is agent-agnostic, so adding new integrations is mostly about figuring out each tool's interception mechanism.\n\n## Limitations \u0026 Security Model\n\nAgentGuard is **defense-in-depth**, not a complete sandbox.\n\n### What AgentGuard Does\n\n- Blocks dangerous shell commands before execution\n- Scans for catastrophic paths (`/`, `~`, `/home`) anywhere in arguments\n- Unwraps wrapper commands (`sudo`, `bash -c`) to find the real command\n- Analyzes script contents before execution (Python, Node, Shell)\n- Provides project-specific rules versioned with your code\n\n### What AgentGuard Does NOT Do\n\n- **Full sandboxing** - Use Docker/containers for true isolation\n- **Binary inspection** - Cannot analyze compiled executables\n- **Network blocking** - Does not prevent data exfiltration\n- **Complete bypass prevention** - A determined attacker can work around pattern matching\n\n### Why Use AgentGuard?\n\nMany 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.\n\nFor 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.\n\n## References\n\n### Official Hook Documentation\n\n- **Claude Code**: [Hooks Documentation](https://code.claude.com/docs/en/hooks)\n- **Cursor**: [Agent Hooks Documentation](https://cursor.com/docs/agent/hooks)\n- **Kiro CLI**: [Hooks Documentation](https://kiro.dev/docs/cli/hooks/)\n\n## Built with\n\nThis project was built using [Kiro](https://kiro.dev) for the Kiroween Hackathon. The rule engine, CLI, and Claude Code integration were all developed with Kiro's assistance.\n\n---\n\nMIT License\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrishkumar%2Fagentguard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrishkumar%2Fagentguard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrishkumar%2Fagentguard/lists"}