API

Guardian keeps its surface area intentionally small: one rules file, one project config, a provider contract, and a focused set of CLI commands. This page explains how those pieces fit together.

Providers

Guardian does not call model APIs directly. It shells out to a provider CLI already installed on your machine, then interprets the result as a local quality gate.

Claude: use the claude CLI when you want strong instruction following and high-quality review output.
Gemini: use the gemini CLI if your team already works inside the Google AI toolchain.
OpenCode: use opencode when you want Guardian to run through an OpenCode-compatible local workflow.
Codex: use the codex CLI when you want Guardian to run with Codex from your local terminal workflow.
Antigravity: use the antigravity CLI when your team runs reviews through an Antigravity-based local workflow.
Provider values can be generic, like opencode, or fully qualified, like opencode:anthropic/claude-opus-4.

AGENTS.md

AGENTS.md is the contract between your team and the AI reviewer. Guardian reads it by default and appends referenced markdown files when you use backtick paths.

# AGENTS.md

## Backend

- Never expose raw database errors in API responses.

- All public functions must include JSDoc.

- Follow `docs/api-rules.md` for endpoint conventions.

What belongs in AGENTS.md

Architecture rules: layering, repository patterns, naming, export conventions.
Quality rules: no any, required tests, error handling, accessibility checks.
Security rules: prevent secret leakage, reject unsafe queries, enforce validation.
Context expansion: reference docs like `docs/api-rules.md` or `docs/ui-rules.md` for scoped enforcement.

Strict Mode

STRICT_MODE controls how Guardian behaves when the provider output is incomplete, malformed, or ambiguous.

STRICT_MODE="true"

When strict mode is true, uncertain output blocks the commit. This is the safest mode for team-wide enforcement.

STRICT_MODE="false"

When strict mode is false, you can choose a more forgiving workflow, but you accept the risk of unclear AI output slipping through.

CLI Commands

These commands cover the full Guardian workflow from bootstrapping a repository to reviewing staged changes and managing cache state.

Command	Description
guardian setup	Interactive guided setup: prompts for rules file name, provider, and hook type, then creates .guardian and AGENTS.md and runs a preview. Detects an existing .guardian and offers to reconfigure.
guardian init	Creates the default .guardian and AGENTS.md files in the current repository.
guardian install	Installs Guardian into .git/hooks/pre-commit so every commit is reviewed automatically.
guardian install --commit-msg	Installs the hook into commit-msg instead of pre-commit when that workflow fits better.
guardian uninstall	Removes Guardian-managed hook blocks from pre-commit and commit-msg.
guardian run	Runs a manual review against staged files.
guardian run --all	Reviews all tracked files in the repository for one-off full audits.
guardian run --pr-mode	Reviews files changed against the configured base branch.
guardian run --ci	Reviews files changed in the latest commit, useful for CI jobs.
guardian cache status	Shows cache state for the current project.
guardian cache clear	Clears the cache for the current project only.
guardian cache clear-all	Clears all Guardian cache data from your machine.

Configuration Skills