The installer copies gga to /usr/local/bin if it is writable, otherwise to ~/.local/bin. If the install directory is not on your PATH, the installer will print the exact line to add to your shell config (~/.bashrc or ~/.zshrc).
WSL is also fully supported — no special configuration needed. Follow the macOS / Linux steps inside your WSL terminal.
Verify the installation:
gga version
2
Initialize your project config
Navigate to your project root and run:
cd ~/your-projectgga init
This creates a .gga config file with all available options and their defaults:
# Gentleman Guardian Angel Configuration# AI Provider (required)# Options: claude, gemini, codex, opencode, ollama:<model>, lmstudio[:model], github:<model>PROVIDER="claude"# File patterns to include in review (comma-separated)FILE_PATTERNS="*.ts,*.tsx,*.js,*.jsx"# File patterns to exclude from review (comma-separated)EXCLUDE_PATTERNS="*.test.ts,*.spec.ts,*.test.tsx,*.spec.tsx,*.d.ts"# File containing code review rulesRULES_FILE="AGENTS.md"# Strict mode: fail if AI response is ambiguousSTRICT_MODE="true"# Timeout in seconds for AI provider responseTIMEOUT="300"
3
Set your AI provider
Open .gga and set PROVIDER to the AI tool you have installed:
Provider
Config value
Notes
Claude
claude
Requires claude CLI
Gemini
gemini
Requires gemini CLI
Codex
codex
npm i -g @openai/codex
OpenCode
opencode
Requires opencode CLI
Ollama
ollama:llama3.2
Replace with your model name
LM Studio
lmstudio
Or lmstudio:model-name
GitHub Models
github:gpt-4o
Replace with your model name
For example, to use a local Ollama model:
PROVIDER="ollama:llama3.2"
See the Providers page for detailed setup instructions for each provider.
4
Create your AGENTS.md
Create an AGENTS.md file in your project root with the coding standards you want enforced. This file is the only input to the AI reviewer — write it clearly.Here is a minimal example:
# Code Review Rules## TypeScript- Use `const` or `let`. Never use `var`.- Prefer interfaces over type aliases for object shapes.- No `any` types. Use `unknown` and narrow with type guards.- All functions must have explicit return type annotations.## React- Use functional components only. No class components.- Use named exports. No default exports.- Keep components under 150 lines. Extract logic into custom hooks.## General- No `console.log` in committed code. Use a logger.- No commented-out code blocks.- Every new function needs a JSDoc comment.
The more specific your rules, the more accurate the review. Vague rules like “write clean code” produce inconsistent results. See Writing your rules file for best practices.
5
Install the pre-commit hook
gga install
This adds GGA to your repo’s .git/hooks/pre-commit file. If a pre-commit hook already exists, GGA is appended to it safely — existing hooks are not overwritten.To install the commit-msg hook variant instead (which also validates the commit message):
gga install --commit-msg
6
Make a commit
Stage your files and commit as normal:
git add src/component.tsxgit commit -m "add user profile component"
GGA runs automatically. You will see output like this on a passing review:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Gentleman Guardian Angel v2.8.0 Provider-agnostic code review using AI━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ℹ️ Provider: claudeℹ️ Rules file: AGENTS.mdℹ️ File patterns: *.ts,*.tsx,*.js,*.jsxℹ️ Cache: enabledFiles to review: - src/component.tsxℹ️ Sending to claude for review (timeout: 300s)...STATUS: PASSEDAll files comply with the coding standards.✅ CODE REVIEW PASSED
On a failing review, the commit is blocked:
STATUS: FAILEDViolations found:- src/component.tsx, line 12 Rule: No `any` types Issue: Parameter `data` is typed as `any`. Use a specific interface or `unknown`.- src/component.tsx, line 34 Rule: Named exports only Issue: Component uses a default export. Change to a named export.❌ CODE REVIEW FAILEDFix the violations listed above before committing.