Skip to content

How do I add guardrails to Claude Code, Codex and Cursor?

Install eslint-plugin-ai-guard and run npx ai-guard init-hooks: it adds hooks to the Claude Code, Codex and Cursor configuration it finds in the project. The hooks feed lint findings back to the agent, stop it once before it finishes if the session introduced problems or weakened checks, and guard git commit --no-verify. A pre-commit gate (npx ai-guard init-git-hook) covers code from any other tool or person.

By the AI Guard maintainers · Last updated · Applies to v1.4.7

Set it up

bash
npm install --save-dev eslint-plugin-ai-guardnpx ai-guard init-hooks                              # agents detected from .claude/, .cursor/, .codex/npx ai-guard init-hooks --agent all --check-installs # all three, plus the package check before installsnpx ai-guard init-git-hook                           # pre-commit gate for everyone

Existing hooks are kept, and running the command again changes nothing. --dry-run shows what would change.

What each agent gets

The same engine runs for every agent; what it can do depends on what each agent's hook system allows.

What AI Guard's hooks do in Claude Code, Codex and Cursor
CapabilityClaude CodeCodexCursor
Lint and weakened checks fed back after each editYesYes (apply_patch)At the finish gate instead
Finish gate: problems the session introduced, raised onceYesYesYes (follow-up message)
Session-start snapshot, so earlier work is not blamed on the agentYesYesYes
Guard on git commit --no-verify and HUSKY=0Asks youDenied; the agent is told to ask youAsks you
Package check before installs (opt-in)Deny or askDenyDeny or ask

Tested: Run against real installs in Claude Code and the Codex CLI. Cursor support follows Cursor’s documented hook format and has not been tested in the editor.

  • Claude Code gets every capability. Findings after each edit go back to Claude, and the finish gate blocks stopping once per new problem.
  • Codex gets feedback after apply_patch edits and the finish gate. Codex hooks cannot ask you a question, so a command that needs your confirmation is denied with a message telling the agent to ask you. Trust the hooks once by running /hooks in Codex.
  • Cursor support follows Cursor's documented hook format and has not been tested in the editor. Cursor's file-edit hook cannot send anything back to the agent, so edit findings arrive at the finish gate as a follow-up message.

The finish gate

When the agent tries to finish, AI Guard compares the working tree with a snapshot taken at session start, so work you did before the session is not blamed on the agent. It reports lint findings on lines the session added or edited, weakened checks, and agent-config issues, once. If the same findings are still there at the next stop, the agent is allowed to stop and you are told instead, so the agent is never stuck in a loop.

The --no-verify guard

git commit --no-verify and HUSKY=0 skip Git hooks. Claude Code and Cursor ask you before such a command runs; Codex denies it and tells the agent to ask you.

How do I stop an AI agent from skipping or weakening tests?

Agents sometimes make a failing build pass by weakening the checks: skipping a test, adding eslint-disable, lowering a coverage threshold, or editing an assertion so it cannot fail. Several checks look for exactly that:

CheckWhat it reports
ai-guard integrityChanges that weaken checks: new eslint-disable or @ts-ignore, skipped or removed tests, lowered coverage or TypeScript settings, removed CI steps
ai-guard changed --test-integrityFocused, skipped, removed or weakened tests, and test scripts that can no longer fail
`no-tautological-assertion`Assertions that pass no matter what, such as expect(true).toBe(true)
`no-assertionless-test`Tests with no assertion
`no-test-env-branch`Production code that returns a fixed result under a test runner

ai-guard verify combines them for a change: a focused test (.only) blocks, and deleted, skipped or weakened tests are reported for you to review, because tests sometimes should change. The finish gate and the pre-commit gate run these checks automatically.

The pre-commit gate

npx ai-guard init-git-hook runs ai-guard verify --staged on every commit through husky, lefthook, simple-git-hooks or the pre-commit framework, whichever agent or person wrote the code. Only problems the commit introduces block it, and it never blocks a commit because AI Guard itself failed.

Limits

  • Cursor support is untested in the editor.
  • People can still skip Git hooks with --no-verify; the agent hooks only flag agents that try.
  • Hooks see what the agent's hook system shows them. Keep a CI check as well; see the GitHub Action.

Frequently asked questions

Does this slow the agent down?

The hook entry point exits in about 0.15 seconds for shell commands that name no package manager, Git or AI Guard, and loads the full engine (about 0.9 seconds) only when it needs to.

Which rules run after each edit?

The agent preset: 8 high-signal rules at error, each one an agent can fix on the spot. Placeholder code and test-integrity rules are checked at the finish gate instead, because agents write stubs on purpose mid-task.

Sources