agentguard

Security guardrails and workflow policies for AI coding agents. Blocks dangerous operations at the hook level — not just as instructions.

Supported agents

Agent	Enforcement
Claude Code	Shell hooks + settings.json + instruction file
Kiro	Shell hooks + agent config + instruction file
Cursor	Project-level hooks + rules/skills (via .cursor/)
Grok	Shell hooks (via ~/.grok/hooks/) + AGENTS.md
OpenAI Codex	Instruction file only (no hook support)

See docs/configuration.md for the full list of enforced rules.

Installation

Homebrew (macOS and Linux)

brew tap SumonMSelim/agentguard
brew install agentguard

apt / deb (Debian, Ubuntu, WSL)

Download the latest .deb from GitHub Releases and install:

VERSION=1.3.0
curl -LO https://github.com/SumonMSelim/agentguard/releases/download/v${VERSION}/agentguard_${VERSION}_all.deb
sudo dpkg -i agentguard_${VERSION}_all.deb

Requires: jq (sudo apt-get install jq).

After installing via either method, install guardrails for your agent:

agentguard claude   # Claude Code
agentguard all      # All agents

Manual

Requires: bash, jq.

# Clone once
git clone https://github.com/SumonMSelim/agentguard.git ~/agentguard

# Bootstrap the `agentguard` CLI (one-time only)
~/agentguard/install.sh claude   # one-time only: bootstraps the `agentguard` CLI wrapper into ~/.local/bin

The script installs the agentguard wrapper to ~/.local/bin/. After this, use the agentguard command for everything:

agentguard claude   # Claude Code
agentguard grok     # Grok
agentguard all      # All agents
agentguard check claude
agentguard uninstall claude
agentguard claude --project --skills go,aws

If ~/.local/bin is not in your PATH, add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Common options:

--dry-run                              # preview changes without writing anything
--skills none                          # skip skill packs
--skills karpathy-guidelines,other     # append specific skills only
--project                              # install to current project directory (skills only)

Re-running is safe — existing files are backed up with a timestamp suffix. settings.json is merged, not overwritten.

Uninstall

agentguard uninstall claude
agentguard uninstall all
agentguard uninstall claude --dry-run   # preview first

Removes only what agentguard owns: hooks, instruction file, Kiro agent config, CLI wrapper. Claude settings.json is surgically unmerged — your own keys untouched, file not deleted.

Check installation status

agentguard check claude
agentguard check all

Reports which hooks, files, settings, and CLI wrapper are present or missing. Exits 1 if anything is out of order — useful in CI to assert guardrails are in place.

Disable per directory

For throwaway projects (pet projects, POCs, sandboxes) where you want the AI to have full access, disable agentguard for that directory:

# In the project root, in your shell (NOT inside Claude):
agentguard disable          # disable in current dir
agentguard enable           # re-enable
agentguard status           # show state for current dir

# Or target another path:
agentguard disable /path/to/poc
agentguard enable  /path/to/poc

Disabling adds the absolute path to ~/.agentguard/disabled-dirs. Every hook reads that file on each tool call and short-circuits (no-op) when the active directory matches an entry or sits below one. Other directories keep their guardrails.

Gated: agentguard disable refuses to run inside a Claude Code session (CLAUDECODE=1), and the Claude Bash(agentguard disable*) permission is denied. The AI cannot disable itself — only you can, from your own shell. Re-enabling is open.

Upgrade

agentguard upgrade

Pulls the latest agentguard, then uninstalls and reinstalls every agent you previously set up — in one step. Your personal settings and skills are preserved.

To check if an update is available without upgrading:

agentguard check claude
# prints an update notice if a newer version exists

Skills

Skills are behavioural packs appended to the agent's instruction file at install time. core skills are included automatically; all others are opt-in via --skills.

Skill	Tags	What it does
karpathy-guidelines	core	Think before coding, simplicity first, surgical changes, goal-driven execution
docker	—	Image security, build efficiency, runtime hardening
go	—	Idiomatic Go: errors, interfaces, concurrency, testing, security
php	—	Modern PHP: strict types, security, PSR standards, architecture
laravel	—	Laravel: thin controllers, Eloquent, queues, security
java	—	Modern Java (17+): design, immutability, security, testing
aws	—	AWS: IAM least privilege, secrets, networking, security posture
gcp	—	GCP: IAM, Workload Identity, Security Command Center
kubernetes	—	K8s: pod security, RBAC, resource limits, HA
terraform	—	Terraform: state management, security, module design, workflow

Global skills

Install once, active in every project. Best for universal practices that apply regardless of stack.

# Core skills only (default)
agentguard claude

# Add language/cloud skills globally
agentguard claude --skills go,aws,kubernetes

# Skip all skills
agentguard claude --skills none

Per-project skills

--project appends skills to the instruction file in the current directory instead of ~. No hooks or settings changes — skills only. Requires agentguard CLI (installed on any global install).

Agent	File written	Notes
Claude Code	.claude/CLAUDE.md in CWD
Codex	AGENTS.md in CWD
Cursor	.cursor/ in CWD (hooks + AGENTS.md)	Always project-local; full install
Grok	AGENTS.md in CWD	Hooks global only (project rules supported)
Kiro	—	Not supported; prints warning

# All agents at once — recommended:
agentguard all --project --skills go,aws

# Or per-agent:
agentguard claude --project --skills go,aws     # → .claude/CLAUDE.md
agentguard codex  --project --skills go,aws     # → AGENTS.md
agentguard grok   --project --skills go,aws     # → AGENTS.md (Grok loads it)
agentguard cursor --skills go,aws               # → .cursor/ (hooks + AGENTS.md)

# Preview without writing:
agentguard all --project --skills go,aws --dry-run

Claude Code loads both ~/.claude/CLAUDE.md (global) and .claude/CLAUDE.md (project) simultaneously — project skills layer on top. Codex checks AGENTS.md in CWD first, then ~/AGENTS.md. Cursor reads only the project-local AGENTS.md.

Recommended pattern: install core skills globally (guardrails apply everywhere), add language and cloud skills per project where relevant.

Adding a skill

Create skills/<name>/SKILL.md with YAML frontmatter (name, tags, description, license) followed by markdown content. Tag core to auto-include on every install. The installer picks it up automatically — no registration needed.

Notes

• Kiro — guardrails only activate when using the agentguard agent. Switch to it in Kiro after install.
• Cursor — guardrails are project-local. agentguard cursor installs .cursor/ into the current directory.
• Grok — native hooks via ~/.grok/hooks/agentguard.json + shared scripts; global rules via ~/AGENTS.md. Grok also loads Claude/Cursor locations for compatibility.
• Codex — instruction-only; no hooks, no automated enforcement backstop.
• block-env.sh — best-effort on the bash surface. block-env-read.sh is the primary layer (intercepts Read/Write/Edit tools directly).
• Protected branches — install prompts for which branches to protect from direct commit/push (default: main,master). Your answer is saved to ~/.agentguard/config and applies across all agents. Override per-shell with export AGENTGUARD_PROTECTED_BRANCHES="main,master,develop".

→ Configuration reference — protected branches, settings.json merge rules, audit log rotation.

License

MIT