Agent Guardrails

Agent Guardrails

**[Chinese](./docs/zh-CN/README.md)** | **English**


`agent-guardrails` checks code changes made by AI coding tools before you merge them. It records what the task is allowed to change, compares that plan with the diff and test evidence, and gives the reviewer a clear result.

It does not replace Claude Code, Codex, Cursor, Gemini, or OpenCode. It works beside them as a repo-level guardrail.

Why use it

AI coding tools are fast, but the hard part is often the handoff:

• What exactly was the agent supposed to change?
• Did it touch files outside the task?
• Were tests or validation actually run?
• Is there evidence a reviewer can trust later?
• Did a small request turn into a broad rewrite?

`agent-guardrails` makes those questions explicit and repeatable.

What it checks

• Scope: flags changes outside the declared task, allowed paths, or intended files.
• Validation: checks reported commands and required evidence files.
• Consistency: warns when a task spreads across too many files or directories.
• Risk: surfaces protected paths, interface changes, config changes, migration changes, and secret-like patterns.
• Reviewer output: prints a score, verdict, findings, next actions, and a concise review summary.
• Agent setup: writes repo-local helper files and MCP configuration guidance for supported agents.

Supported agents

`agent-guardrails` can generate or update helper files for:

Agent	Helper location
Claude Code	CLAUDE.md
Codex	.codex/instructions.md
Cursor	.cursor/rules/agent-guardrails-enforce.mdc
Gemini CLI	GEMINI.md
OpenCode	.opencode/rules/agent-guardrails-enforce.md

Requirements

• Node.js 18+
• Git
• A git repository for the project you want to protect

The npm package includes native runtime binaries for Windows x64, macOS x64/arm64, and Linux x64. It also includes the Node runtime.

Quick start

npm inst