# gentleman-guardian-angel: AI code review as a pre-commit hook

> A pure Bash tool that runs your staged files past a model of your choice against an AGENTS.md rules file, so coding standards get checked before a commit lands instead of three reviews later.

**Gentleman-Programming/gentleman-guardian-angel** — 😇 Gentleman Guardian Angel (gga) - Provider-agnostic code review using AI. Use Claude, Gemini, Codex, Ollama to enforce your coding standards.

- Repository: https://github.com/Gentleman-Programming/gentleman-guardian-angel
- Stars: 1,189 · Forks: 166
- Language: Shell
- License: MIT
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/gentleman-programming-gentleman-guardian-angel

## The problem it starts from is a review that arrives too late

The stated motivation is blunt: you have coding standards, your team ignores them, and code reviews catch issues too late. gentleman-guardian-angel, usually called gga, responds by putting an AI review between `git commit` and the repository. Staged files get validated against an `AGENTS.md` file, and the commit either passes or fails with details explaining what went wrong.

The repository is MIT licensed, version 2.10.1, written in Shell, with 1163 stars and 160 forks. It is not archived and the last push was on 2026-07-08, which lines up with the v2.10.1 release published the same day. The README states the design constraint plainly: pure Bash core, works everywhere, with individual providers possibly needing their own CLI or API tooling.

That split is the interesting part of the architecture. The core has no runtime framework and no language runtime to install, while the model access is delegated. That is what lets the provider list be long without the tool becoming a package with a dependency tree.

## Getting installed through Homebrew or a shell script

There are three install paths in the README, and the first is a single line:

```bash
brew install gentleman-programming/tap/gga
```

The manual path clones the repository and runs the bundled installer:

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

Windows gets its own variant because the shells differ. The installer also creates `~/bin/gga.bat` so `gga` works from cmd.exe and PowerShell, and the README is careful to point out that the `.bashrc` change only affects Git Bash. For PowerShell and cmd.exe you need `%USERPROFILE%\bin` on the Windows user PATH. WSL needs no special handling at all.

One trap is worth knowing before you install. Oh My Zsh ships a `git` plugin that defines a `gga` alias, and it collides with the CLI, producing `git: 'gui' is not a git command.` The README's fix is one line in `.zshrc`, after the Oh My Zsh source line:

```bash
unalias gga 2>/dev/null
```

The badges claim macOS, Linux and Windows via Git Bash, Bash 5.0 or newer, and 266 passing tests.

## Eleven providers behind one config value

The provider table is the centre of the tool, and the pattern is consistent: a short config value plus a link to wherever that provider is installed. Claude, Gemini, Codex, OpenCode, Kiro take a bare name. Cursor Agent, Kilo, LM Studio and MiniMax accept an optional `:model` suffix. Ollama and GitHub Models require one.

```bash
gga init                # Create .gga config
gga install             # Install git hook
gga run --pr-mode
```

You write your standards into `AGENTS.md`, set `PROVIDER` in the `.gga` config, and the tool reads both. The docs list makes clear this is a broader system than the README shows: `docs/rules-file.md` covers writing an effective rules file and mentions a skill-based approach, while `docs/configuration.md` covers the config file, options, hierarchy and environment overrides.

The releases show the provider list growing recently rather than being theoretical. v2.10.0 added Kiro CLI support and, notably, kept the full review prompt out of argv by using a stdin and temp-file handoff, passing only a short instruction to the headless command. v2.9.0 added Cursor Agent, Kilo and MiniMax, and moved API payloads off argv as well. Getting a large prompt through a provider CLI's argument list is a real engineering problem, and the fact that two consecutive releases fixed it says something useful about the current state.

## Hook, CI and pull request modes are separate commands

The command list is short enough to read in one pass, and the split between local and remote runs is the part that matters. `gga run` reviews staged files. `gga install` puts that behind a standard pre-commit hook, and `gga install --commit-msg` adds a commit message hook instead. `gga uninstall` removes them.

For automation there are two separate paths. `gga run --ci` reviews the last commit, which is what a pipeline step needs. `gga run --pr-mode` reviews the full set of PR changes rather than the most recent commit, which is the difference between reviewing a diff and reviewing a branch.

`gga run --no-cache` forces a fresh review, `gga config` prints the resolved configuration, and `gga cache status` reports what the cache holds. `gga version` is the obvious one.

The integrations page lists Husky, pre-commit, Lefthook, VS Code and CI/CD as supported, which suggests the intended reading is that gga is one participant in whatever hook system you already run rather than a replacement for it.

## Caching is what makes per-commit latency tolerable

Every commit that triggers a model call needs to be tolerable, and that is what the caching layer is for. The README summarises it as smart caching: skip unchanged files. `docs/caching.md` is the page that goes further, covering how invalidation works and which commands control it.

The consequence for the user is that reviewing the same file twice in a row costs almost nothing, so the practical workflow is to run the review constantly rather than saving it for a pre-push ritual. `gga run --no-cache` exists for the case where you have just edited the rules file itself and want to know whether the new rules changed the verdict.

The project also builds its own test image, which is the part of the Makefile that reveals how the team treats this. The model used for tests is small and local, with Ollama as the default service and a configurable model variable:

```
OLLAMA_MODEL ?= tinyllama
DOCKER_COMPOSE = docker compose
```

That is a sensible call for testing a Bash tool that shells out to a provider: the test suite does not need a frontier model to check argument construction, caching and timeout cleanup. The repository tree backs this up with a `.shellspec` directory and a `spec/` directory, so the suite is shellspec rather than a hand-rolled harness.

## Where the README stops and the docs take over

The README is a well-organised index that stops at exactly the right place. Ten documentation pages cover configuration, the rules file, providers, commands, caching, integrations, examples, troubleshooting and the changelog, with CONTRIBUTING.md describing an issue-first workflow. Anything you would want to do beyond the basic hook flow is in one of those files rather than in the README.

That is the shape a small tool should have, and it is also where to look for the gaps. The README tells you what the commands are and which providers exist. It does not tell you how to write a rules file that produces useful verdicts rather than a token-burning loop over obvious style points, and that is the actual difficulty of using an AI reviewer. The docs list names `rules-file.md` as covering writing an effective AGENTS.md, so the answer exists.

The other limit is structural and worth stating without hedging. gga reviews text through a provider. It does not run your build, your tests or your linter, so anything your existing tooling already catches is redundant here, and what remains is judgement calls about conventions and structure. Used as a second reviewer alongside real checks, the design is sound. Used as the only check, it leaves obvious gaps.

## Conclusion

What makes this tool useful is not the model call, it is the placement. A review that runs on staged files at commit time catches the same class of problem as a comment three pull requests later, at a fraction of the annoyance, and doing it from Bash means the only thing a contributor installs is a script. The honest limits are equally clear: it reviews text through a provider CLI, it cannot know what your build does, and a rules file nobody maintains turns into noise. Start by writing a short AGENTS.md you would actually defend, run `gga run` on staged changes before installing the hook, then pick a provider from the matrix and leave model selection to your CLI unless the docs describe a reason.

## FAQ

### What is gentleman-guardian-angel and how does it fit into a git workflow?

It is a pure Bash tool that reviews staged files against an AGENTS.md rules file using an AI provider you choose. `gga install` sets it up as a standard pre-commit hook, so `gga run` runs automatically on every commit and passes or fails with details. `gga uninstall` removes it.

### Which AI providers does gga support?

The README table lists Claude, Gemini, Codex, OpenCode, Cursor Agent, Kilo, Kiro, Ollama, LM Studio, GitHub Models and MiniMax. Claude, Gemini, Codex, OpenCode and Kiro take a bare config value, while Cursor Agent, Kilo, LM Studio and MiniMax accept an optional model suffix. Ollama and GitHub Models require a model to be named.

### How do I install it on Windows?

Clone the repository and run `bash install.sh` from Git Bash, PowerShell or cmd.exe. The installer creates `~/bin/gga.bat` so the command works from cmd.exe and PowerShell, and you need `%USERPROFILE%\bin` on the Windows user PATH because a `.bashrc` change only affects Git Bash. WSL needs no extra setup.

### Why does gga conflict with Oh My Zsh?

The Oh My Zsh git plugin, which is enabled by default, defines a `gga` alias that shadows the CLI and makes git report `git: 'gui' is not a git command.` Adding `unalias gga 2>/dev/null` to your `.zshrc` after the Oh My Zsh source line clears the collision.

### Does gga work in CI, or only locally?

Both. `gga run --ci` reviews the last commit for pipeline use, and `gga run --pr-mode` reviews the full set of pull request changes rather than a single commit. The docs also list Husky, pre-commit, Lefthook, VS Code and CI/CD integrations.

## Sources

- [Gentleman-Programming/gentleman-guardian-angel on GitHub](https://github.com/Gentleman-Programming/gentleman-guardian-angel)
- [Issues](https://github.com/Gentleman-Programming/gentleman-guardian-angel/issues)
- [License: MIT](https://github.com/Gentleman-Programming/gentleman-guardian-angel/blob/main/LICENSE)
- [README](https://github.com/Gentleman-Programming/gentleman-guardian-angel/blob/main/README.md)
- [Releases](https://github.com/Gentleman-Programming/gentleman-guardian-angel/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gentleman-programming-gentleman-guardian-angel