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

| Agent | Injection file | Auto-read level | |-------|---------------|-----------------| | Claude Code | CLAUDE.md | ⭐⭐⭐ System | | Cursor | .cursor/rules/agent-guardrails-enforce.mdc | ⭐⭐⭐ System | | OpenCode | .opencode/rules/agent-guardrails-enforce.md | ⭐⭐⭐ System | | Codex | .codex/instructions.md | ⭐⭐⭐ System | | Gemini CLI | GEMINI.md | ⭐⭐⭐ System |

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

| Before | After | |--------|-------| | "AI changed 47 files, no idea why" | "AI changed 3 files, all in scope" | | "Tests probably passed?" | "Tests ran: 12 passed, 0 failed" | | "That looks like a new pattern" | "⚠️ Parallel abstraction detected" | | "Hope nothing breaks" | "✓ Safe to merge, residual risk: low" |

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

| Layer | Mechanism | Effect | |-------|-----------|--------| | L1: enforce | Inject into agent system-level instruction files | ⭐⭐⭐ Strongest — auto-read by AI | | L2: AGENTS.md | Project-level rule file | ⭐⭐ Medium — AI may ignore | | L3: pre-commit hook | Git commit interception | ⭐⭐⭐ Safety net — enforced |

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

Competitor Comparison

| Feature | CodeRabbit | Sonar | agent-guardrails | |---------|-----------|-------|------------------| | Pre-generation constraints | ❌ Post-comment | ❌ Post-check | ✅ | | Scope control | ❌ | ❌ | ✅ | | Task context | ❌ | ❌ | ✅ | | Test relevance checks | ❌ | ❌ | ✅ |

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
    }
  }
}

| Field | Default | Values | Description | |-------|---------|--------|-------------| | violationSeverity | "error" | "error" | "warning" | Severity for scope violations. "error" blocks merge; "warning" lets acknowledged violations pass. | | violationBudget | 5 | Number | Minor scope slips within this count are surfaced as soft warnings instead of hard errors. Only applies when explicit scope (allowedPaths, intendedFiles) is not configured. |

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)

| Field | Default | Description | |-------|---------|-------------| | maxChangedFilesPerTask | 20 | Maximum files per task before warning | | maxTopLevelEntries | 3 | Maximum unique top-level directories | | maxBreadthMultiplier | 2 | Breadth multiplier for change diffusion |

Correctness (checks.correctness)

| Field | Default | Description | |-------|---------|-------------| | requireTestsWithSourceChanges | Preset-dependent | Require test file changes when source files change | | requireCommandsReported | Preset-dependent | Require validation commands to be reported as run | | requireEvidenceFiles | true | Require evidence file to exist |

Scoring (scoring)

| Field | Default | Description | |-------|---------|-------------| | weights | Category defaults | Per-category weights (scope, validation, consistency, continuity, performance, risk), auto-normalized to 100 |

Risk (checks.risk)

| Field | Default | Description | |-------|---------|-------------| | requireReviewNotesForProtectedAreas | true | Require review notes when touching protected paths | | warnOnInterfaceChangesWithoutContract | true | Warn on interface changes not in task contract | | warnOnConfigOrMigrationChanges | true | Warn on config/migration file changes |

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 activate <license-key>
agent-guardrails pro report
agent-guardrails pro workbench --open
agent-guardrails pro workbench --live
agent-guardrails pro workbench --native-panel

pro activate delegates license activation to the installed Pro package and stores only the Pro-owned local activation cache. If a personal license reaches its device limit, the OSS CLI shows the limit, current device, and Pro-provided next action instead of only returning an error code. pro report prints the optional Pro go-live report when @agent-guardrails/pro is installed. pro workbench now prints a compact non-HTML panel preview first, then writes the local Workbench view contract plus a native panel model. pro workbench --native-panel asks the packaged Rust runtime to render that panel model when available, falling back to the JavaScript preview if the native renderer is not present yet. workbench-panel can also render the same saved panel model directly; it uses the native runtime when available and keeps a JavaScript fallback for older or source-checkout installs. pro workbench --open opens the live surface when available, so users can review the ship or no-ship answer without inspecting raw JSON. pro workbench --live renders the Pro Workbench from the structured view contract first, with legacy HTML only as a fallback for older Pro versions. It includes refresh, rerun, current-loop, next-proof, short-loop, visible-check completion, and evidence-note actions, shows the current agent handoff with copyable Codex and Claude Code execution packages plus the rerun command, can export the whole handoff bundle into local files for the next agent step, automatically saves proof notes after each run, and keeps a readable summary of the last proof loop on the same page. Visible verification has its own watch list and finish-and-rerun path, so users can stay in one UI instead of bouncing between the browser, the terminal, and raw JSON. If Pro is absent or unlicensed, OSS behavior stays unchanged.

When @agent-guardrails/pro exposes Pro MCP tools, the OSS MCP server lists and calls them dynamically. This lets existing MCP-capable agents read Pro Workbench data through the same agent-guardrails mcp connection without moving Pro decision logic into the OSS package.

CLI Reference

| Command | Purpose | |---------|---------| | setup --agent <name> | Initialize project | | enforce --all | Enforce rules (recommended) | | unenforce --all | Remove enforcement | | plan --task "..." | Create task contract | | check --review | Run reviewer-facing guardrail check | | generate-agents | Generate agent-specific config files | | doctor | Diagnose current installation | | pro status | Show optional Pro install and license status | | pro activate | Activate the optional Pro package without writing license keys to repo config | | pro report | Print the optional Pro go-live report | | pro workbench | Write, open, or serve the optional local Pro workbench | | pro cleanup | Preview or apply Pro proof memory cleanup | | workbench-panel | Render a local Workbench panel model with the native runtime | | start | Start daemon | | stop | Stop daemon | | status | Show daemon status |

Install & Update

# Install
npm install -g agent-guardrails

# Update
npm update -g agent-guardrails

Docs

• CHANGELOG
• Workflows
• Troubleshooting
• Proof
• Benchmarks

License

MIT