CommitBrief is a local-first CLI that runs an LLM review over your git diff before a teammate — or your future self — sees it. There's no server and no telemetry; the diff leaves your machine only for the provider you chose, and with a local model like Ollama it never leaves at all.

The interesting engineering isn't "call an LLM." It's everything that has to happen around that call so the review stays cheap, safe, and reproducible. Here's the whole path from commitbrief --staged to the findings on your screen.

TL;DR

• What it is — a CLI that reviews your staged diff (or any git diff range) with the provider you pick: Claude, GPT, Gemini, or a fully local Ollama model.
• The non-obvious part — the LLM call is one stage out of fourteen. Filtering, a pre-send secret scan, content-addressed caching, and a cost preflight do most of the work.
• The limit — it's the zeroth reviewer, not a replacement for a human one.

Key facts

• Go 1.25, GPL-3.0-or-later, no hosted service.
• 10 providers + a mock: Anthropic, OpenAI, Gemini, Ollama (native APIs); DeepSeek, Mistral, Cohere (OpenAI-compatible); claude-cli, gemini-cli, codex-cli (subprocess-backed).
• The review path is read-only. The single git-write command is commitbrief commit, and even that only runs one git commit of already-staged changes — it never edits a file.
• Install: brew install CommitBrief/tap/commitbrief, scoop install commitbrief, or go install github.com/CommitBrief/commitbrief/cmd/commitbrief@latest.

The shape of a review

Every review walks one linear pipeline. Here it is at altitude before we zoom in:

Five of these carry most of the weight. Let's take them in order.

Getting the diff: go-git, with git as the source of truth

You'd think reading a diff is trivial. It is — until you need staged-vs-unstaged, a worktree comparison, and git diff main...feature to all behave exactly like git, on Windows too.

CommitBrief runs a hybrid: a primary go-git implementation with a git CLI fallback (ADR-0002). Range operations that go-git models cleanly — commit-vs-first-parent, merge-base range diffs, branch diffs — stay in-process. Staged, unstaged, and arbitrary git diff <args> passthrough shell out to git with --no-color --no-ext-diff for stable parsing. The CLI stays the source of truth for index and worktree state; reimplementing that plumbing is exactly the kind of subtle drift you don't want under a review tool.

commitbrief --staged                 # the index
commitbrief --unstaged               # the working tree
commitbrief diff main...feature      # args forwarded verbatim to git diff

Filtering: three layers, so the model never reads noise

A diff is mostly signal and a pile of things no reviewer should read. Filtering is three composed layers (ADR-0006):

1. Built-ins — around 65 patterns: lock files, vendor/**, node_modules/**, generated code, build artifacts, binaries, IDE/OS noise, and .commitbrief/cache/**.
2. .commitbriefignore — gitignore syntax, repo-root, team-shared. It composes after the built-ins with last-match-wins, so a !pattern line can re-include something a built-in dropped.
3. Semantic prose — natural-language exclusions in COMMITBRIEF.md ("don't flag generated mocks"), applied by the model itself.

After the ignore layers, --file / --dir apply a narrower allowlist. If nothing survives, the run exits 0 having spent nothing — an empty diff is a success, not an error.

The guard nobody else runs: don't send secrets to the model

Stage 5 is the one I care about most, because it sits on the boundary where your code is about to leave the machine.

Two checks run before the provider call. First, a guard refuses to quietly ship your own config: if any path in the diff starts with .commitbrief/, it prompts, and auto-aborts when there's no TTY. Second, a secret scanner runs over added lines only against eight built-in patterns — AWS access keys, GitHub/GitLab tokens, Anthropic/OpenAI keys, JWTs, Stripe live keys, PEM private keys — and you can add your own through guard.secret_patterns.

One detail I'm proud of: a match records only {Line, Patterns} — never the matched substring. The scanner that exists to stop a leak can't itself become one through a log line, stderr, or a cache file.

The bypass policy is deliberate, too. --allow-secrets skips the scan; --yes does not. Auto-confirming prompts in a pipeline should never silently approve shipping a credential to a third party.

Caching is just content addressing

Reviewing the same diff twice should be free. The cache key is a SHA-256 over the exact inputs that could change the answer:

sha256( diff "::" systemPrompt "::" provider ":" model ":" lang ":" schemaVersion [":ctx"] [":mode:"+mode] )

Every input earns its place. The fully-assembled system prompt is in the key, so editing COMMITBRIEF.md invalidates stale reviews. The schema version is in the key, so bumping the output contract invalidates everything at once. --with-context and the commit-message mode each get a suffix so they never collide with a plain review. Entries are written atomically — temp file, 0600, then rename — to .commitbrief/cache/<key>.json: one file per response, no index.

The payoff lands at stage 8. Cost preflight estimates input tokens with a conservative (len+3)/4 heuristic, clamps expected output to [200, 1500] tokens, multiplies by a per-model price table, and prompts only when the estimate clears your cost.warn_threshold_usd (default $0.50). A cache hit skips preflight entirely — re-running a review on an unchanged diff costs one disk read.

The call, and what happens when the model misbehaves

For API providers, CommitBrief asks for structured findings and parses them into a fixed contract — severity, file, line, title, description, suggestion — emitted as JSON schema v1. If the model returns something unparseable, it retries once; if it's still bad, it degrades to rendering the raw text as Markdown and prints a warning instead of crashing. CLI-backed providers (claude-cli, gemini-cli, codex-cli) run as read-only subprocesses and stream their text verbatim.

Output is Cards by default, or:

commitbrief --json --fail-on=high       # CI gate: exit 1 on any high+ finding
commitbrief diff main...feature --markdown -o review.md

Exit codes stay simple: 0 for success — including a clean review or a --fail-on threshold that wasn't breached — and 1 for any error or a breached gate.

What it is not

It's the zeroth reviewer, not a replacement for a human one. It catches the obvious-but-easy-to-miss class: injection, missing nil checks, swallowed errors, a guard clause that's now unreachable. It does not catch intent-level design problems, and it won't tell you whether the feature should exist. That conversation stays with your reviewer.

I won't assert quality at you, either. There's a reproducible eval harness scoring real output against a known-answer corpus — run it yourself:

COMMITBRIEF_EVAL_PROVIDER=<name> make eval-live

If you want a second pair of eyes on your diff before anyone else gets one — locally, with the provider you already trust — that's the whole point:

commitbrief setup     # pick a provider, paste a key, ping it
commitbrief init      # optional: write project-specific rules
git add .
commitbrief --staged

Repo and install instructions: github.com/CommitBrief/commitbrief.

This is part 1 of **Building CommitBrief. Next: how one Go interface fans out to 10 LLMs across three transport classes — native APIs, OpenAI-compatible endpoints, and subprocess-backed CLIs.