// blog

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-hook writes a pre-commit hook that blocks the commit on a critical finding. Use the pre-commit framework 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.

HookWhat it reviewsBlocks on
pre-commit (default)The staged change setA critical finding
commit-msgSame body as pre-commit, but runs after the message is composedA critical finding
pre-pushEach 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-verify skips the pre-commit and commit-msg hooks, and git push --no-verify skips pre-push. A hook is a convenience for the person committing, not an enforcement point. For enforcement, run a gate job in CI as well.
  • A degraded review does not block. If the model returns unparseable output, --fail-on is 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


← all posts