Configuration
Guardian loads configuration from multiple sources with a well-defined precedence order. Understanding this order lets you override settings per-project or globally without touching code.
Configuration Precedence
When Guardian starts, it merges configuration sources in this order. Later sources override earlier ones.
- 1Environment variables (highest priority)
- 2Project .guardian file at the repository root
- 3Global config at ~/.config/guardian/config
- 4Built-in defaults (lowest priority)
The .guardian File
The .guardian file is a plain key=value dotfile at the root of your repository. Running guardian setup or guardian init generates a default version you can customize.
# .guardian
PROVIDER="claude"
FILE_PATTERNS="*.ts,*.tsx,*.js,*.jsx"
EXCLUDE_PATTERNS="*.test.ts,*.spec.ts,*.stories.tsx"
RULES_FILE="AGENTS.md"
STRICT_MODE="true"
TIMEOUT="300"
CACHE="true"
Supported Configuration Keys
| Key | Description |
|---|---|
| PROVIDER | The AI provider CLI to use. Defaults to claude. |
| FILE_PATTERNS | Comma-separated glob patterns of files to include in the review. |
| EXCLUDE_PATTERNS | Comma-separated glob patterns to exclude from review. |
| RULES_FILE | Path to the rules file Guardian reads. Defaults to AGENTS.md. |
| STRICT_MODE | When true, ambiguous or incomplete provider output blocks the commit. |
| TIMEOUT | Maximum seconds to wait for the provider response before failing. Default: 300. |
| PR_BASE_BRANCH | The base branch used in --pr-mode to determine changed files. |
| CACHE | Enable or disable content-based caching. Default: true. |
Environment Variables
Any configuration key can be overridden at runtime via environment variables. This is useful for CI/CD pipelines or one-off runs.
| Variable | Description |
|---|---|
| GUARDIAN_PROVIDER | Override the active provider |
| GUARDIAN_TIMEOUT | Override the provider timeout in seconds |
| GUARDIAN_STRICT_MODE | Override strict mode (true/false) |
| GUARDIAN_RULES_FILE | Override the rules file path |
| GUARDIAN_CACHE | Override caching (true/false) |
Provider Values
The PROVIDER key accepts these values. OpenCode also supports the colon notation when you want to target a specific model.
PROVIDER="claude"
PROVIDER="gemini"
PROVIDER="opencode"
PROVIDER="codex"
PROVIDER="antigravity"
PROVIDER="opencode:anthropic/claude-opus-4"