AgentTrail Guard: open-source guardrails for AI coding agents

Check your AI coding agent's commands and file changes before they run. Works with Claude Code, Cursor, and Codex CLI. Local, free, and no account needed.

Quick start · Guardrails · Reference · Changelog

AgentTrail Guard is a free, open-source CLI that connects to your coding agent's hooks and checks every tool call that reaches them against 74 inspectable guardrails before it runs. Guard can block a matching call, send it to you for approval, or record it as a warning, depending on the agent. When nothing matches, your agent's normal permission flow continues.

Quick start

You need: Node.js 20 or newer, npm, and at least one of Claude Code, Cursor, or Codex CLI.

1. Install Guard

npm install -g @agenttrail/guard

2. Connect each agent you use

agenttrail-guard init --agent claude   # Claude Code
agenttrail-guard init --agent cursor   # Cursor
agenttrail-guard init --agent codex    # Codex CLI

Each setup is independent, and settings are shared under ~/.agenttrail/guard/. To see exactly what init would change first, add --print; it changes nothing.

init demonstrates the engine by evaluating a synthetic rm -rf / and showing its decision. The command is never executed. This checks the engine; you still need to complete your agent's setup below.

3. Finish agent setup and check status

• Claude Code: restart Claude Code to load the plugin.
• Cursor: use the agent in an editor window. Check Cursor's Hooks tab, and restart Cursor if Guard's entries do not appear.
• Codex CLI: start Codex, open /hooks, and approve each agenttrail-guard entry. Guard does not run until you approve it.

agenttrail-guard status

status shows what is enforcing in each agent, recent decisions, and settings that need attention. For Codex, ON means the hook is installed and well-formed; confirm approval in Codex's own /hooks screen, because Guard cannot read that state.

Upgrading and uninstalling

To upgrade, install the latest release, re-run init for each agent you use, and restart that agent. Your settings are kept, and Codex keeps the approval you already gave. Before 1.0, a minor release can include a breaking change, so skim the changelog first.

npm install -g @agenttrail/guard@latest
agenttrail-guard init --agent claude   # and again for cursor or codex, if you use them

To remove Guard from an agent, run uninstall for it. It removes only what Guard added, and keeps your settings in ~/.agenttrail/guard/.

agenttrail-guard uninstall --agent claude   # or: --agent cursor, --agent codex

What each step changes is covered in Updating and Uninstall.

Prefer a guided walkthrough? See the AgentTrail Guard installation guide.

Why AgentTrail Guard?

A real Claude Code session. The agent decides to reset the database to get a schema push through; Guard blocks prisma db push --force-reset with dd.accept-data-loss before it runs.

Your coding agent runs shell commands and edits files all day, faster than you can review each one. Most of those calls are exactly what you want. The ones that aren't, like git reset --hard over a day of uncommitted work, rm -rf on the wrong path, terraform apply -auto-approve, or a read of your .env, tend to be the ones you can't take back. Guard puts a rule-based check on every tool call that reaches its hooks, in every session, so the risky ones stop and explain themselves before they run, and everything else carries on as normal.

• Local, with no account. Guard runs on your machine and needs no sign-up. Out of the box it makes no network calls; the one exception is crash reporting, which is off unless you turn it on.
• Rules you can read. Every guardrail is plain data with a title, severity, default action, and a description of what it deliberately misses.
• Tunable without turning it off. Allow one command shape for one rule, change a rule's action, disable a pack, or add your own rule.
• One rule set across agents. Claude Code, Cursor, and Codex CLI share the same settings in ~/.agenttrail/guard/.
• See what it caught. agenttrail-guard status shows recent decisions, and scan turns past agent sessions into a self-contained HTML report.
• Apache-2.0. The matching engine and hooks live in this repository; the rule library lives in agenttrailhq/guardrails.

How AgentTrail Guard works

1. Your agent proposes a tool call. Its hook sends Guard the tool name and inputs.
2. Guard evaluates it locally. The engine matches supported command and path fields against the bundled guardrails and your custom rules, applying your settings.
3. Your agent receives a decision. A matching rule can block, ask, or warn; each agent handles these differently.
4. You can inspect the result. Matched calls are recorded in a local, scrubbed decision log; agenttrail-guard status shows recent decisions.

Guard uses rule matching, not an LLM reviewing your code. It can stop a matching call only when your agent sends it through the installed hooks, it does not inspect file contents, and it does not guarantee that every dangerous action will be caught. On an internal error it fails open: your agent's normal permission flow continues. Read the coverage and runtime limits before relying on it.

See AgentTrail Guard in action

The table below is real output: each row is a Claude Code PreToolUse call passed to Guard's hook, and the reason Guard returned before anything ran.

In a real Claude Code session, an agent told it was only dev data reached for npx prisma db push --force-reset, and dd.accept-data-loss blocked it before it ran. Read the case study.

Every decision names its guardrail, and every guardrail explains itself (the description is wrapped and trimmed here):

$ agenttrail-guard guardrails show wt.reset-hard

  wt.reset-hard                        working-tree · severity: high
  git reset --hard discards uncommitted work

  Action        block   (shipped default)
  Enforcing     yes

  Discards every uncommitted change in the working tree, irrecoverably — there is no
  reflog for work that was never committed. Does NOT match `git restore` (see
  wt.restore-path), `git checkout -- .` (see wt.checkout-discard) [...]

What Guard catches

Guard ships with 74 guardrails across 11 packs. Packs are named for the harm they prevent, not the technique used to spot it. By default, 13 guardrails block, 50 ask, and 11 warn.