Agent Guardrails

Chinese | English

agent-guardrails is a merge gate for AI-generated code. It checks that AI changes match expectations before you merge.

• 🎯 Scope validation — AI only touches allowed files
• ✅ Test verification — tests must pass
• 🔍 Drift detection — catches parallel abstractions, interface changes
• 🛡 Protected paths — critical files stay untouched
• 🔒 Security hygiene — warns on hardcoded secrets, unsafe patterns, sensitive file changes
• 📊 Trust score — 0-100 composite score with graduated verdicts
• 🔧 Auto-fix — Tier-1 issues fixed automatically, zero side effects
• 🧬 Mutation testing — optional lightweight built-in slice catches vacuous tests (config-gated, default-disabled)

Who it is for

agent-guardrails is aimed first at solo developers and small teams already using AI coding tools.

• solo founders shipping real product code with Claude Code, Cursor, Codex, Gemini, or OpenCode
• small product teams that want the same repo guardrails even when each developer uses a different agent
• consultants and agencies that need safer AI-assisted changes across multiple client repos

It is not primarily for one-off toy prompts or teams looking to replace their coding agent entirely.

Prerequisites

• Node.js 18+
• Git — your project must be a git repository (git init). All change detection relies on git diff.

Quick Start

# 1. Install
npm install -g agent-guardrails

# 2. Set up in your project (must be a git repo)
cd your-repo
agent-guardrails setup --agent claude-code

# 3. Enforce rules (recommended)
agent-guardrails enforce --all

Supports 5 agents: claude-code, cursor, opencode, codex, gemini.

How It Works

Core Workflow

1. Setup — Initialize your project

agent-guardrails setup --agent <your-agent>

This automatically:

• ✅ Generates .agent-guardrails/config.json
• ✅ Generates/appends AGENTS.md
• ✅ Injects a git pre-commit hook
• ✅ Creates AI tool config files (MCP)

2. Enforce — Make AI follow the rules (recommended)

The AGENTS.md from setup is advisory. AI agents may ignore it. enforce injects guardrail instructions directly into each agent's system-level auto-read files (like CLAUDE.md, GEMINI.md), which take far higher priority.

# Enforce for all supported agents
agent-guardrails enforce --all

# Or a specific agent
agent-guardrails enforce --agent claude-code

# See which agents are supported
agent-guardrails enforce --help

Remove enforcement (safely preserves your existing content):

agent-guardrails unenforce --all
agent-guardrails unenforce --agent claude-code

3. Daily workflow

After setup, the AI automatically runs checks before finishing tasks:

agent-guardrails check --base-ref HEAD~1

Results appear directly in the chat. The git pre-commit hook provides a safety net.

Manual check (optional):

agent-guardrails check --review

4. Plan a task (optional)

Keep the AI focused by creating a task contract first:

agent-guardrails plan --task "Add user authentication"

Before vs After

Why this beats a DIY plugin stack

Many users already have Claude Code, Cursor, Codex, or Gemini plus custom prompts, hooks, and MCP tools.

The reason to use agent-guardrails is not that those tools cannot generate code.
It is that a DIY stack still leaves a lot of manual work around:

• defining repo-safe boundaries before implementation
• checking whether the diff stayed inside those boundaries
• proving validation actually ran
• summarizing residual risk for a human reviewer
• keeping repeated AI edits from slowly fragmenting the repo

agent-guardrails is strongest when users want to keep their current coding agent and add a repeatable trust layer on top.

Three-layer Enforcement

Recommended: setup + enforce --all = double protection.

Competitor Comparison

Key difference: define boundaries before code generation, not after discovering problems.

Configuration

All settings live in .agent-guardrails/config.json, created by setup. Key sections:

Scope (checks.scope)

Controls how out-of-scope file changes are handled.

{
  "checks": {
    "scope": {
      "violationSeverity": "error",
      "violationBudget": 5
    }
  }
}

Tip: Keep violationSeverity at "error" (default) for safety-first workflows. Lower to "warning" only for exploratory prototyping where scope flexibility is acceptable.

Consistency (checks.consistency)

Correctness (checks.correctness)

Scoring (scoring)

Risk (checks.risk)

Pro (optional)

The OSS package is a complete merge gate. Pro is optional and only activates when the separate Pro package is installed and licensed.

Check local Pro availability:

agent-guardrails pro status
agent-guardrails pro report
agent-guardrails pro workbench --open

pro report prints the optional Pro go-live report when @agent-guardrails/pro is installed. pro workbench --open writes and opens the optional local Pro operator workbench so users can review the ship/no-ship decision without inspecting raw JSON. If Pro is absent or unlicensed, OSS behavior stays unchanged.

CLI Reference

Install & Update

# Install
npm install -g agent-guardrails

# Update
npm update -g agent-guardrails

Docs

• CHANGELOG
• Workflows
• Troubleshooting
• Proof
• Benchmarks

License

MIT