How It Works

A step-by-step breakdown of the Saguaro review flow.

1. OVERVIEW

1Your rules (.saguaro/rules/*.md)
2     +
3Git diff (base..HEAD)
4     +
5Codebase context (import graph, blast radius)
6     ↓
7AI checks each changed file against matching rules
8     ↓
9Violations found → prints them, exits 1
10Nothing found   → silence, exits 0

Saguaro takes your team's rules, the git diff of your current changes, and rich codebase context (an import graph and blast radius analysis), then uses an AI agent to check each changed file against the rules that apply to it. If a rule is violated, Saguaro prints the violation and exits with code 1. If nothing is wrong, Saguaro stays silent and exits with code 0.

2. RULES MATCHING

2.1Saguaro loads rules from .saguaro/rules/ — each rule is a markdown file with YAML frontmatter that specifies which files the rule applies to via glob patterns.

2.2Changed files (from git diff) are matched against each rule's glob patterns using minimatch. Only rules whose globs match a changed file are applied to it.

2.3Rules can include and exclude files using glob patterns. Prefix a glob with ! to exclude matching files.

2.4If a rule specifies no globs, it applies to all changed files by default.

3. CODEBASE CONTEXT

3.1Saguaro builds an import graph of your codebase using tree-sitter and SWC parsers. This graph maps which files import from which other files across your project.

3.2For each changed file, Saguaro computes the "blast radius" — the set of files that import from the changed file (dependents) and the files it depends on (dependencies).

3.3Blast radius is computed via BFS traversal up to a configurable depth (default: 1). This gives the reviewer enough context to understand how a change propagates through the codebase without overwhelming the model.

3.4Context is token-budgeted to fit within model limits. If the full blast radius exceeds the budget, Saguaro prioritizes the most closely related files.

Build the import graph

1sag index

Run sag index to build the import graph before your first review. Saguaro will also build the index automatically if one doesn't exist.

4. REVIEW EXECUTION

4.1Changed files are grouped into batches for review. Batch size is configurable via files_per_batch in your config (default: 2).

4.2Each batch is reviewed by an AI agent that receives the matched rules and codebase context. The agent analyzes the diff alongside the surrounding code to check for violations.

4.3The agent uses tool calls to read file contents and analyze code. This allows it to inspect the full file beyond the diff when needed to understand context.

4.4Saguaro supports multiple AI providers: Anthropic, OpenAI, and Google. Configure your provider in .saguaro/config.yaml.

5. OUTPUT

5.1Console output (default) — violations are printed with the file path, line number, rule ID, severity, and a description of the violation.

5.2JSON output (--output json) — structured output for CI integration. Each violation is a JSON object with all the same fields.

5.3Exit codes — 0 means clean, no violations found. 1 means violations were detected.

5.4Verbose mode (--verbose) — shows detailed progress including which rules matched which files, batch composition, and model responses.