GuardianIntegrationProviders
Docs Navigation
IntroductionInstallationQuick StartConfigurationAPISkillsChangelog

Quick Start

Install Guardian from npm, connect it to your repository, and run your first AI-powered pre-commit review in a few minutes.

npm package

@ajosecortes/guardian-cli

Open npm package

1. Install Guardian from npm

Guardian is published as @ajosecortes/guardian-cli and exposes the guardian binary. Choose the installation mode that best fits your workflow.

  • Node.js 22 or newer
  • A Git repository you want to protect
  • At least one supported provider CLI installed and authenticated
01

Global install

Recommended when you want the guardian command available in any repository on your machine.

$ npm install -g @ajosecortes/guardian-cli

02

One-off with npx

Useful when you want to try Guardian without keeping a global installation on your system.

$ npx @ajosecortes/guardian-cli setup

03

Project dependency

Install it inside a repository when you prefer versioning the CLI with the project itself.

$ npm install -D @ajosecortes/guardian-cli

Tip: If your goal is the smoothest onboarding, install globally first. It gives you a stable guardian command for setup, run, and future reconfiguration.

2. Verify the CLI and run guardian setup

After installation, confirm the binary is available and then run guardian setup inside your Git repository. This interactive flow creates your configuration, installs the hook you choose, and finishes with a preview run to confirm everything is wired correctly.

$ guardian --help

> Shows available commands and confirms the binary is installed

$ guardian setup

> Launches the interactive setup flow and finishes with a preview run

  • .guardian — your project configuration (provider, patterns, cache settings)
  • AGENTS.md — review rules written in plain Markdown for the AI to follow

3. Follow the guided setup flow

guardian setup guides you through three decisions so you do not need to remember multiple commands or flags during onboarding.

Step 01

Choose the rules file name and provider: Claude, Gemini, OpenCode, Codex, or Antigravity.

Step 02

Generate .guardian and AGENTS.md, then decide whether Guardian should hook into pre-commit or commit-msg.

Step 03

Finish with a preview guardian run. If a .guardian file already exists, Guardian detects it and asks whether you want to reconfigure.

Tip: If Guardian detects an existing .guardian file, it switches to reconfiguration mode instead of blindly overwriting your setup.

4. Tune your review rules

Once setup finishes, open AGENTS.md and .guardian to define what the AI must enforce on every commit and which provider should execute the review. Rules are plain Markdown — no special syntax required. You can reference other files using backtick notation.

# AGENTS.md

## Global Rules

- Never expose raw database errors in API responses.

- All exported functions must have JSDoc comments.

- UI components must follow: `docs/ui-rules.md`

## TypeScript

- No use of the any type. Use unknown instead.

- All async functions must handle their errors explicitly.

5. Make your first commit

Stage your changes and commit as normal. Guardian intercepts the commit, analyzes your staged files against your rules, and returns one of two outcomes:

$ git add .

$ git commit -m "feat: initial setup"

> Guardian running pre-commit review...

> Analyzing 3 staged files with claude

> STATUS: PASSED — commit applied

STATUS: PASSED

STATUS: PASSED — the commit goes through immediately

STATUS: FAILED

STATUS: FAILED — the commit is blocked with feedback

Next Steps