Gentleman-Programming/gentleman-guardian-angel — stars, momentum and ranking

😇 Gentleman Guardian Angel (gga) - Provider-agnostic code review using AI. Use Claude, Gemini, Codex, Ollama to enforce your coding standards.

Provider-agnostic code review using AI

Use Claude, Gemini, Codex, OpenCode, Cursor Agent, Kilo, Kiro, Ollama, LM Studio, GitHub Models, MiniMax, or any AI to enforce your coding standards.

Pure Bash core. Works everywhere.

Version License Bash Platforms Homebrew Tests PRs Welcome

Installation • Quick Start • Providers • Commands • Docs

Example

🎯 Why?

You have coding standards. Your team ignores them. Code reviews catch issues too late.

GGA runs on every commit, validating staged files against your AGENTS.md. Like having a senior developer review every line before it hits the repo.

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│   git commit    │ ──▶ │  AI Review   │ ──▶ │  ✅ Pass/Fail   │
│  (staged files) │     │  (any LLM)   │     │  (with details) │
└─────────────────┘     └──────────────┘     └─────────────────┘

🔌 Provider agnostic — Claude, Gemini, Codex, OpenCode, Cursor Agent, Kilo, Kiro, Ollama, LM Studio, GitHub Models, MiniMax
📦 Pure Bash core — no runtime framework; individual providers may require their own CLI or API tooling
🪝 Git native — Standard pre-commit hook
⚡ Smart caching — Skip unchanged files
🔍 PR review mode — Review full PRs, not just last commit
🪟 Cross-platform — macOS, Linux, Windows (Git Bash), WSL

📦 Installation

Homebrew (recommended)

brew install gentleman-programming/tap/gga

Manual

git clone https://github.com/Gentleman-Programming/gentleman-guardian-angel.git
cd gentleman-guardian-angel
./install.sh

Windows (Git Bash, PowerShell, cmd.exe)

git clone https://github.com/Gentleman-Programming/gentleman-guardian-angel.git
cd gentleman-guardian-angel
bash install.sh
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

On Windows, the installer also creates ~/bin/gga.bat so gga can be called from cmd.exe and PowerShell. Add %USERPROFILE%\bin to your Windows user PATH for those shells; .bashrc only affects Git Bash.

WSL is also fully supported — no special configuration needed.

Oh My Zsh users

If you use Oh My Zsh with the git plugin enabled (the default), the alias gga will conflict with this CLI. You'll see:

git: 'gui' is not a git command. See 'git --help'.

Fix: Add this line to your ~/.zshrc after the Oh My Zsh source line:

unalias gga 2>/dev/null

Then run source ~/.zshrc or open a new terminal.

🚀 Quick Start

cd ~/your-project
gga init                # Create .gga config
gga install             # Install git hook
# Edit .gga to set your PROVIDER
# Create AGENTS.md with your coding standards
# Done — every commit gets reviewed 🎉

🔌 Providers

Provider	Config Value	Installation
Claude	`claude`	claude.ai/code
Gemini	`gemini`	gemini-cli
Codex	`codex`	`npm i -g @openai/codex`
OpenCode	`opencode`	opencode.ai
Cursor Agent	`cursor[:model]`	cursor.com
Kilo	`kilo[:model]`	`npm install -g @kilocode/cli`
Kiro	`kiro`	kiro.dev/downloads
Ollama	`ollama:`	ollama.ai
LM Studio	`lmstudio[:model]`	lmstudio.ai
GitHub Models	`github:`	marketplace/models
MiniMax	`minimax[:model]`	platform.minimax.io

📖 See docs/providers.md for detailed examples and setup.

📋 Commands

Command	Description
`gga init`	Create sample `.gga` config
`gga install`	Install pre-commit hook
`gga install --commit-msg`	Install commit-msg hook
`gga uninstall`	Remove hooks
`gga run`	Review staged files
`gga run --ci`	Review last commit (CI/CD)
`gga run --pr-mode`	Review full PR changes
`gga run --no-cache`	Review ignoring cache
`gga config`	Show configuration
`gga cache status`	Show cache info
`gga version`	Show version

📖 See docs/commands.md for detailed usage.

📚 Documentation

Topic	Description
Configuration	`.gga` config file, options, hierarchy, env overrides
Rules File	Writing effective `AGENTS.md`, best practices, skill-based approach
Providers	Detailed setup for each AI provider
Commands	Full command reference with examples
Caching	How smart caching works, invalidation, commands
Integrations	Husky, pre-commit, Lefthook, VS Code, CI/CD
Examples	Real-world walkthrough, project configs
Troubleshooting	Common issues and fixes
Changelog	Version history
Contributing	How to contribute (issue-first workflow)

📄 License

Built with 🧉 by developers who got tired of repeating the same code review comments