Skip to main content
GGA is configured through a .gga file in your project root. Options can also be set globally or overridden with environment variables.

​
Config file format

Run gga init to create a starter .gga file, or create it manually:
.gga
# AI Provider (required)
# Options: claude, gemini, codex, opencode, ollama:<model>, lmstudio[:model], github:<model>
PROVIDER="claude"

# File patterns to review (comma-separated globs)
# Default: * (all files)
FILE_PATTERNS="*.ts,*.tsx,*.js,*.jsx"

# Patterns to exclude from review (comma-separated globs)
# Default: none
EXCLUDE_PATTERNS="*.test.ts,*.spec.ts,*.d.ts"

# File containing your coding standards
# Default: AGENTS.md
RULES_FILE="AGENTS.md"

# Fail if AI response is ambiguous (recommended for CI)
# Default: true
STRICT_MODE="true"

# Timeout in seconds for AI provider response
# Default: 300 (5 minutes)
TIMEOUT="300"

# Base branch for --pr-mode (auto-detects main/master/develop if empty)
# PR_BASE_BRANCH="main"

​
Config options

​
PROVIDER
string
required
The AI provider to use for code review. Must be set in at least one config source.Accepted values:
ValueProvider
claudeAnthropic Claude Code CLI
geminiGoogle Gemini CLI
codexOpenAI Codex CLI
opencodeOpenCode CLI (default model)
opencode:<model>OpenCode CLI with a specific model (e.g. opencode:anthropic/claude-opus-4-5)
ollama:<model>Ollama with the specified local model (e.g. ollama:llama3.2)
lmstudioLM Studio local server (uses currently loaded model)
lmstudio:<model>LM Studio with a specific model (e.g. lmstudio:llama-3.2-3b-instruct)
github:<model>GitHub Models API (e.g. github:gpt-4o)
​
FILE_PATTERNS
string
default:"*"
Comma-separated glob patterns for files to include in the review. Patterns are matched against the file’s full path and its basename.
# Review only TypeScript and JavaScript files
FILE_PATTERNS="*.ts,*.tsx,*.js,*.jsx"

# Review only Python files
FILE_PATTERNS="*.py"

# Review all files (default)
FILE_PATTERNS="*"
​
EXCLUDE_PATTERNS
string
Comma-separated glob patterns for files to exclude from the review. Applied after FILE_PATTERNS. No files are excluded by default.
# Exclude test and type declaration files
EXCLUDE_PATTERNS="*.test.ts,*.spec.ts,*.test.tsx,*.spec.tsx,*.d.ts"

# Exclude Go test files and mock files
EXCLUDE_PATTERNS="*_test.go,*.mock.ts"
​
RULES_FILE
string
default:"AGENTS.md"
Path to the file containing your coding standards. The file contents are sent to the AI as the review ruleset. Relative paths are resolved from the directory where gga is run.
# Default
RULES_FILE="AGENTS.md"

# Custom path
RULES_FILE="docs/CODE-REVIEW-RULES.md"
​
STRICT_MODE
string
default:"true"
Controls how GGA handles ambiguous AI responses — those that contain neither STATUS: PASSED nor STATUS: FAILED in the first 15 lines of output.
  • true — treat ambiguous responses as failures (recommended for CI/CD)
  • false — allow the commit to proceed when the response is ambiguous
# Fail on ambiguous response (default, recommended)
STRICT_MODE="true"

# Allow commit on ambiguous response
STRICT_MODE="false"
​
TIMEOUT
string
default:"300"
Maximum number of seconds to wait for the AI provider to respond before timing out. If the timeout is exceeded, GGA exits with an error in strict mode or allows the commit in non-strict mode.
# Default: 5 minutes
TIMEOUT="300"

# Increase for large changesets or slow connections
TIMEOUT="600"
​
PR_BASE_BRANCH
string
default:"auto-detect"
The base branch to diff against when running gga run --pr-mode. When not set, GGA automatically detects the base branch by checking for main, master, and develop in that order.
# Explicit base branch
PR_BASE_BRANCH="main"

# Leave commented out to use auto-detection (default)
# PR_BASE_BRANCH="main"

​
Configuration hierarchy

GGA merges configuration from three sources. Higher-priority sources override lower ones:
PrioritySourceLocation
1 (highest)Environment variablesGGA_PROVIDER, GGA_TIMEOUT
2Project config.gga in the project root
3 (lowest)Global configPlatform-specific path (see below)
This means you can set a global default provider in ~/.config/gga/config and override it per project in .gga, or override both with an environment variable for a single run.

​
Global config file

The global config file follows the same format as .gga. GGA resolves its path based on your platform: 
~/.config/gga/config
If the XDG_CONFIG_HOME environment variable is set, GGA uses $XDG_CONFIG_HOME/gga/config instead.
# Create the directory and global config
mkdir -p ~/.config/gga
cat > ~/.config/gga/config << 'EOF'
PROVIDER="claude"
TIMEOUT="300"
EOF

​
Environment variable overrides

These environment variables override the corresponding config file settings for a single run or the entire shell session:
VariableOverridesDescription
GGA_PROVIDERPROVIDEROverride the AI provider
GGA_TIMEOUTTIMEOUTOverride the response timeout (seconds)
GGA_CI_SOURCE_COMMIT(none)Override the source commit in --ci mode (default: HEAD~1)
GGA_NO_SPINNER(none)Set to any value to disable the animated spinner in TTY mode
GGA_TRACE(none)Set to any value to enable internal debug tracing output
# Override provider for a single run
GGA_PROVIDER="gemini" gga run

# Override provider for the session
export GGA_PROVIDER="ollama:llama3.2"

# Override timeout for a single run
GGA_TIMEOUT=600 gga run

# Review from a specific commit in CI
GGA_CI_SOURCE_COMMIT=abc1234 gga run --ci

# Disable spinner (useful when output is piped)
GGA_NO_SPINNER=1 gga run

# Enable debug tracing
GGA_TRACE=1 gga run

​
Inspecting the current config

Run gga config to see which config files were found and what values are currently active: 
gga config

  Config Files:
    Global:  /Users/you/.config/gga/config
    Project: .gga

  Values:
    PROVIDER:          claude
    FILE_PATTERNS:     *.ts,*.tsx,*.js,*.jsx
    EXCLUDE_PATTERNS:  *.test.ts,*.spec.ts,*.d.ts
    RULES_FILE:        AGENTS.md
    STRICT_MODE:       true
    TIMEOUT:           300s
    PR_BASE_BRANCH:    auto-detect

  Rules File: Found
Run gga init to generate a starter .gga file with all options documented inline. It’s safe to run in an existing project — GGA will prompt before overwriting.

Build docs developers (and LLMs) love

Get started for freeTalk to us