Introduction
guardian-cli is a framework for AI-assisted code review — local gatekeepers that are safe, predictable, and run natively inside your Git hooks.
What is Guardian?
Most code review integrations treat the process as asynchronous. Developers build features, commit the code, push to origin, and then wait for CI pipelines to run or for humans to review. The feedback loop itself is slow.
Guardian is different. The AI evaluates the code exactly where you write it. It inspects staged files and intercepts your commits, builds a context-aware prompt relative to your changes, and evaluates your code against project rules in real time.
The challenge is that unconstrained AI output during local development can be unpredictable. It can hallucinate issues, trigger false positives, or misunderstand complex logic. You need a way to let AI be creative with feedback while keeping it constrained to deterministic exit codes bounding your projects.
That is what guardian-cli does. You define a collection of rules. AI runs your staged diff constrained to that logic. Our hooks process the result natively — blocking the commit or passing it gracefully — with content-based caching and no arbitrary latency.
Features
- Git hook integration for pre-commit workflows
- Configurable provider support: Claude, Gemini, OpenCode, Codex, and Antigravity
- Project-level and global configuration via .guardian files
- Rule loading from AGENTS.md with support for referenced markdown files
- Content-based cache to skip unchanged files — zero latency on re-runs
- Parallel file reading for faster reviews on large commits
- CLI commands for setup, init, install, run, uninstall, and cache management
How Guardian Works
1. Define your rules
A project declares what AI must verify using standard markdown files, such as AGENTS.md.
# AGENTS.md
## Global Rules
- Prevent API endpoints from returning raw database errors.
- Check UI guidelines: `docs/ui-rules.md`
- All public functions must have JSDoc comments.
Guardian also expands backtick file references inline. If docs/ui-rules.md exists, its contents are appended to the prompt automatically.
2. AI evaluates the commit
When you run git commit, the CLI runs analysis using your preferred provider CLI (Claude, Gemini, OpenCode, Codex, or Antigravity).
$ git commit -m "feat: add user auth"
> Guardian intercepting pre-commit hook...
> Provider: claude — analyzing 4 staged files
> Cache: 2 hits, 2 files sent for review
3. Your workflow continues
If the analysis yields STATUS: PASSED, the commit applies instantly. The unchanged content is hashed and cached. On failure, the commit is blocked before it reaches origin.
STATUS: PASSED
Commit applies instantly. Result is hashed and cached for future runs.
STATUS: FAILED
Commit is blocked before reaching origin. Feedback is printed to the terminal.