How to set up AI code review in a pre-commit hook.
Three ways to run an AI review before every commit or push: the install-hook scaffolder, the pre-commit framework, or a hand-written hook. Commands and trade-offs.
An AI code review pre-commit hook is a script git runs just before it records a commit; it sends the staged diff to a language model and aborts the commit if a finding is severe enough. CommitBrief gives you three ways to set one up, and the shortest is a single command.
In short:
commitbrief install-hookwrites apre-commithook that blocks the commit on a critical finding. Use thepre-commitframework integration if your team already manages hooks that way, or write your own hook if you need a different threshold.
The full flag reference is on the Git hooks page, and Review before you commit is the guided walkthrough. The reasoning for reviewing at this point is in Review before the push. This post is the setup. If you would rather run the review on a pull request than on your machine, see AI code review in GitHub Actions without a bot.
Before you start
The hook calls the CLI, so CommitBrief needs a configured provider. If commitbrief --staged already works in the repo, you are ready. If not, run commitbrief setup first; the first-review guide walks through it. For a hook that never leaves your machine, configure Ollama as in running AI code review locally with Ollama.
Option 1: install-hook
commitbrief install-hook # default: pre-commit
commitbrief install-hook --hook=pre-push
commitbrief install-hook --uninstall # remove, only if CommitBrief wrote it
The default writes .git/hooks/pre-commit. Its body runs:
commitbrief --staged --fail-on=critical --quiet --no-cost-check
Two of those flags exist because nobody is at the keyboard. --no-cost-check skips the cost preflight prompt that would otherwise stop an expensive diff, and --quiet drops the progress output. The threshold is fixed at critical; install-hook has no flag to change it.
| Hook | What it reviews | Blocks on |
|---|---|---|
pre-commit (default) | The staged change set | A critical finding |
commit-msg | Same body as pre-commit, but runs after the message is composed | A critical finding |
pre-push | Each ref being pushed, as commitbrief diff <remote>..<local> | The first critical finding |
For pre-push, new branches are reviewed as the tip commit only, and branch deletions are skipped. That new-branch behavior requires v1.18.1 or later, and the hook is a generated file: re-run commitbrief install-hook --hook=pre-push --yes after upgrading to regenerate it.
Two behaviors protect existing setups. If a hook file already exists, install-hook refuses until you pass --yes, which first backs the old file up to <name>.bak.<UTC timestamp>. And --uninstall only removes a hook carrying the Generated by `commitbrief install-hook` marker, so a hand-written hook is never deleted.
The generated hook embeds the absolute path of the commitbrief binary, so it also works from GUI git clients that strip your shell PATH. Hooks that survive Tower, GitHub Desktop, and JetBrains covers why that matters.
Option 2: the pre-commit framework
If the repo already uses the pre-commit framework, add CommitBrief to .pre-commit-config.yaml instead of running install-hook:
repos:
- repo: https://github.com/CommitBrief/commitbrief
rev: <released-tag> # pin a released tag, e.g. the latest from the releases page
hooks:
- id: commitbrief # the framework builds and pins the binary
Use id: commitbrief-system to run a commitbrief that is already on your PATH instead of letting the framework build one. Then install the framework’s hook once per clone:
pre-commit install
Both ids review the staged changes with --staged --fail-on=high, so they block on high or worse, one level stricter than the install-hook default. Neither id passes --no-cost-check, so on a large staged diff the cost preflight can stop the commit when the estimate passes the warning threshold; add the flag to args if you want that off. Override args to change the gate:
hooks:
- id: commitbrief
args: [--staged, --fail-on=critical]
Pick one approach per repo. The framework owns .git/hooks/, so running both against the same hook causes a conflict.
Option 3: your own hook
To use a threshold the scaffolder does not offer, write .git/hooks/pre-commit yourself and make it executable:
#!/bin/sh
exec commitbrief --staged --fail-on=medium --quiet --no-cost-check
Unlike the generated hook, this one finds commitbrief through PATH, so a GUI client may not find it. Use the absolute path if you commit from one. The values --fail-on accepts, and the exit codes, are in Severity and CI gating.
What a hook costs you
- Latency on every commit. The hook waits for the model. A local model or a fast API model keeps that tolerable; a slow one trains people to bypass it.
- Spend on every commit. An API provider bills each review. The local response cache means re-running the same staged diff does not call the provider again, but each new diff does. Ollama has zero pricing.
- It is bypassable.
git commit --no-verifyskips thepre-commitandcommit-msghooks, andgit push --no-verifyskipspre-push. A hook is a convenience for the person committing, not an enforcement point. For enforcement, run agatejob in CI as well. - A degraded review does not block. If the model returns unparseable output,
--fail-onis skipped by design and the commit goes through. - Old code can trip it. On a legacy repo, baseline the pre-existing findings first; see Brownfield adoption.
The hook reviews the diff, so it catches the pattern-level problems a tired reviewer misses. It will not tell you whether the change was the right one to make. Compare approaches in AI code review tools: CLI vs GitHub App vs IDE.
One action
Run commitbrief install-hook in a throwaway branch, stage a change, and commit. If the first review is too slow for daily use, change the provider before you roll the hook out to a team.
Related reading
- Jul 26, 2026v1.13 → v1.15: replacing inference with evidence
Three releases that look unrelated — a JSON parser change, one config key, four new commands — and the single direction underneath them: every claim CommitBrief makes should be something it can show you, and the ones that don't need a model shouldn't call one.
- Jun 30, 2026Hooks that survive Tower, GitHub Desktop, and JetBrains.
Why git hooks installed from the command line silently fail when you commit from a GUI client — and the absolute-path embedding trick that makes commitbrief install-hook just work everywhere.
- May 31, 2026Review before the push: why the strongest review window is right before `git commit -m`.
Why CommitBrief defaults to --staged scope. Reviewing a change that hasn't entered history yet is always cheaper than patching it with a force-push.