# CommitBrief

> CommitBrief is a provider-agnostic, local-first CLI that runs LLM-powered code reviews on git diffs — staged, unstaged, single commit, branch, or PR-style range. Open source under GPL-3.0. Source: https://github.com/CommitBrief/commitbrief

Every link below is a markdown mirror of the page, not its HTML. For the whole site inlined in a single file, fetch https://commitbrief.com/llms-full.txt.

Current CLI version: v1.16.0 (released 2026-07-30).

## Docs

- [Getting started](https://commitbrief.com/docs/1.x/getting-started.md): What CommitBrief is, who it's for, and how the local LLM review pipeline fits into a developer's workflow.
- [Installation](https://commitbrief.com/docs/1.x/installation.md): Install the CommitBrief CLI on macOS, Linux, or Windows via Homebrew, Scoop, go install, or pre-built binaries.
- [Upgrading — upgrade](https://commitbrief.com/docs/1.x/upgrade.md): commitbrief upgrade checks GitHub Releases and installs a newer CommitBrief using the right mechanism for however the binary got there — delegating to Homebrew, Scoop, or go install, and SHA-256-verifying a manual replacement. No automatic update check, no telemetry.
- [Run your first review](https://commitbrief.com/docs/1.x/first-review.md): Three commands from a fresh CommitBrief install to your first structured code review on staged changes.
- [Review scopes](https://commitbrief.com/docs/1.x/review-scopes.md): How to scope a CommitBrief review — staged, unstaged, arbitrary diff ranges, commit-level filters by author and date, path allow/deny filters, and the three-layer ignore pipeline.
- [Commit graph — map](https://commitbrief.com/docs/1.x/commit-graph.md): commitbrief map draws the commit DAG and highlights exactly which commits a filter selected, so you can check a filter before paying for a review. --branches switches to a branch topology summary. Deterministic, no provider call, always exits 0.
- [Output formats](https://commitbrief.com/docs/1.x/output-formats.md): Cards, JSON, markdown, --copy, --compact, --verbose — every way CommitBrief renders review findings.
- [Flaky-test detector](https://commitbrief.com/docs/1.x/flaky-tests.md): A deterministic, provider-free pre-pass that flags timing-dependent and unseeded-random anti-patterns in changed test files before any model call.
- [Review a GitHub PR — remote pr](https://commitbrief.com/docs/1.x/remote-pr.md): commitbrief remote pr reviews a GitHub pull request via the gh CLI, posts findings as inline comments, and submits an approve / comment / request-changes verdict.
- [Summarize changes — summary](https://commitbrief.com/docs/1.x/summary.md): commitbrief summary explains a set of changes in plain language — a read-only digest grouped by logical area, attributed to the short commit hash for a range.
- [Signal control — baseline and suppression](https://commitbrief.com/docs/1.x/signal-control.md): Cut repeat noise without hiding findings from review — a user-private baseline that accepts a brownfield repo's existing findings, plus inline commitbrief-ignore comments with a visible reason.
- [Architecture-aware review](https://commitbrief.com/docs/1.x/architecture-review.md): Feed an architecture.json — the config of the sibling tool archlint, declaring layers and their allowed import edges — into the review prompt, so the reviewer can flag a diff that crosses a declared architectural boundary. A one-way read; CommitBrief never lints or enforces.
- [Severity and CI gating](https://commitbrief.com/docs/1.x/severity.md): The five-level severity scale, --fail-on semantics, exit codes, and recipes for wiring CommitBrief into pre-commit hooks and CI pipelines.
- [Generate a commit message — commit](https://commitbrief.com/docs/1.x/commit.md): commitbrief commit turns your staged diff into a commit message with --type formats and --generate alternatives, then runs git commit after you confirm.
- [Configuration](https://commitbrief.com/docs/1.x/configuration.md): Two-tier YAML config, environment variables, the config subcommand, and every key CommitBrief reads at runtime.
- [Review rules — COMMITBRIEF.md and OUTPUT.md](https://commitbrief.com/docs/1.x/review-rules.md): Customise the system prompt your reviewer sees (COMMITBRIEF.md) and how findings render to markdown locally (OUTPUT.md template).
- [Providers](https://commitbrief.com/docs/1.x/providers.md): Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Cohere, Ollama, claude-cli, gemini-cli, codex-cli — when to pick which, plus per-provider config and pricing.
- [MCP server — agent review gate](https://commitbrief.com/docs/1.x/mcp-server.md): commitbrief mcp runs a Model Context Protocol server over stdio so an AI agent or host can call CommitBrief as a self-review gate before it submits code. One review tool, the same pipeline as commitbrief --json, structured findings back.
- [Policy gate — guard](https://commitbrief.com/docs/1.x/policy-gate.md): A declarative merge gate that caps how many findings of each severity a change may carry, via an opt-in .commitbrief/policy.yml. Richer than a single --fail-on threshold; aimed at gating high-volume, often AI-authored, pull requests.
- [GitHub Action — review in CI](https://commitbrief.com/docs/1.x/github-action.md): CommitBrief/commitbrief-action runs the CLI on every pull request — inline review comments, a severity gate, or a declarative policy gate.
- [Git hooks](https://commitbrief.com/docs/1.x/git-hooks.md): Block bad commits at pre-commit, commit-msg, or pre-push with a one-command CommitBrief hook scaffolder.
- [Credential audit — leaks](https://commitbrief.com/docs/1.x/leaks.md): commitbrief leaks scans every tracked file plus the added lines of your git history for committed credentials — the same pattern set the review path uses, with no provider call, no cache, and no cost. Exits 1 on a hit, so it gates CI out of the box.
- [Safety, cost, and cache](https://commitbrief.com/docs/1.x/safety-and-cost.md): Three pre-send guards — secret scanner, .commitbrief/ guard, cost preflight — plus the local response cache and how to manage it.
- [Timeouts — --timeout](https://commitbrief.com/docs/1.x/timeouts.md): --timeout bounds a whole CommitBrief run and raises the hard cap each provider enforces on its own — the CLI tools' 5 minutes, ollama's 5, the Anthropic SDK's 10 — because a context deadline can only cut a run short, never lengthen it.
- [Troubleshooting](https://commitbrief.com/docs/1.x/troubleshooting.md): commitbrief doctor + recipes for common failures — wrong version, missing credentials, malformed JSON, guard aborts, OUTPUT.md template errors.

## Blog

- [Proving the review happened: SOC2, audit chains, and the compliance angle of `--json`.](https://commitbrief.com/blog/proving-the-review-happened.md): What auditors actually ask when they say 'every commit was reviewed,' and how CommitBrief's JSON output and cache-key design fit into an audit chain — without overpromising what an LLM review can be evidence of.
- [Multi-provider as an architecture decision: why locking to one LLM is a reliability problem.](https://commitbrief.com/blog/provider-fallback-strategy.md): Anthropic, OpenAI, Gemini, Ollama, claude-cli, gemini-cli — the provider abstraction in v1.0 and the manual-switch posture that keeps single-provider outages from breaking your workflow.
- [The cost of a junior waiting for a senior, and what an LLM can — and can't — do about it.](https://commitbrief.com/blog/junior-senior-review-loop.md): A junior's 30-minute change ties up six hours of a senior's time. The LLM isn't a mentor, but it can be the assistant that frees senior time for actual mentorship.
- [Onboarding through review rules: nobody reads CONTRIBUTING.md, but everyone reads their PR feedback.](https://commitbrief.com/blog/onboarding-via-review-rules.md): A `COMMITBRIEF.md` your team has actually written becomes the most effective onboarding document for new hires — because it shows up where they're already paying attention.
- [Where your AI reviewer runs matters.](https://commitbrief.com/blog/where-your-ai-reviewer-runs.md): CodeRabbit, Greptile, Copilot review, and Bugbot compared with a local CLI: where each runs, who holds the key, what leaves your machine.
- [Blocking vs. nitpicking: shaping review tone with `OUTPUT.md`.](https://commitbrief.com/blog/output-md-tone-of-voice.md): Encoding team norms into the review output. Severity scales, finding format, what gets surfaced and what gets quietly suppressed.
- [Cross-timezone review lag, and turning the reviewer from blocker into validator.](https://commitbrief.com/blog/cross-timezone-review-lag.md): The hidden tax on async teams: a junior's PR waits for a reviewer who's asleep, then for one who's in a meeting. An LLM in the middle of that chain doesn't replace anyone — it changes what waiting means.
- [Signal from noise: the three-layer filter that keeps reviews readable.](https://commitbrief.com/blog/three-layer-filtering.md): Built-in defaults, `.commitbriefignore`, and `COMMITBRIEF.md` semantic filtering — how they compose, last-wins semantics, and how negative patterns revert a default.
- [Your diff should never leave your machine: the Ollama path for air-gapped repos.](https://commitbrief.com/blog/air-gapped-with-ollama.md): How CommitBrief runs LLM code review with zero network egress. For SOC2-restricted repos, defense work, fintech and healthcare codebases — and an honest look at the quality trade-off.
- [The solo developer's missing second pair of eyes.](https://commitbrief.com/blog/solo-developer-second-pair-of-eyes.md): For OSS maintainers, indie hackers, side-project builders — there's no one to review your code. What an LLM fills in, and what it deliberately doesn't.
- [v1.13 → v1.15: replacing inference with evidence](https://commitbrief.com/blog/replacing-inference-with-evidence.md): 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.
- [`commitbrief compress`: an LLM rewriting another LLM's system prompt — and the discipline that keeps it safe.](https://commitbrief.com/blog/compress-deep-dive.md): Three compression levels, atomic apply, automatic backup, and the rule that refuses to shrink your rules file if the result isn't actually smaller.
- [`commitbrief doctor`: the diagnostic I wish more CLIs shipped.](https://commitbrief.com/blog/commitbrief-doctor.md): Eight checks against the resolved environment, plus a per-provider connection ping — what doctor inspects, why warnings are non-blocking by design, and the CI pattern that gates merges on a clean health check.
- [How a single JSON schema survives four very different LLM providers.](https://commitbrief.com/blog/structured-output-across-llms.md): Anthropic tools mode, OpenAI strict response_format, Gemini ResponseSchema, Ollama format:json — four mechanisms, one contract. How CommitBrief's findings schema v1 stays stable across them, and the retry-once-then-degrade fallback for when it doesn't.
- [Three flags into one subcommand: the `commitbrief diff` collapse and what it taught me about CLI surface area.](https://commitbrief.com/blog/commitbrief-diff-subcommand.md): v0.9.0 retired --commit, --branch, and --pull-request in favour of a single 'diff' subcommand that pass-throughs to git diff. A note on why reinventing what git already does is the wrong shape.
- [Subprocess providers: reusing a subscription you're already paying for.](https://commitbrief.com/blog/subprocess-providers.md): How claude-cli and gemini-cli wrap a host CLI as a subprocess instead of calling an API, what they give up to do that, and why stdin transport matters when the diff gets large.
- [Hooks that survive Tower, GitHub Desktop, and JetBrains.](https://commitbrief.com/blog/hooks-in-gui-git-clients.md): 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.
- [`--fail-on`: turning an LLM review into a CI gate without locking yourself in.](https://commitbrief.com/blog/fail-on-ci-gate.md): How severity-based exit codes work, why graceful degrade deliberately skips the gate, and what 'fail at critical or worse' actually means inside your pipeline.
- [Three guards before any token is spent.](https://commitbrief.com/blog/pre-send-guards.md): The secret scanner, the cost preflight, and the .commitbrief/ guard — three pre-send checks that fire before CommitBrief talks to a provider, and why --yes deliberately doesn't bypass two of them anymore.
- [v1.0 is an API freeze: what `schema: v1` actually promises.](https://commitbrief.com/blog/api-freeze-v1.md): v1.0 isn't just a number. CLI flag surface, JSON schema v1, and the COMMITBRIEF.md / OUTPUT.md formats are under strict semver from here on. Here's what that buys you, and what it stops me from doing.
- [Why a CLI, not a GitHub App.](https://commitbrief.com/blog/cli-vs-github-app.md): On trigger ownership when picking a code review tool. The design thinking behind CommitBrief as a CLI — and when that's the wrong choice.
- [Anatomy of a `COMMITBRIEF.md`: turning team tribal knowledge into a system prompt.](https://commitbrief.com/blog/commitbrief-md-anatomy.md): What a good rules file looks like, what doesn't belong in it, and why the LLM's effectiveness as a zeroth reviewer depends on the file being written well.
- [Review before the push: why the strongest review window is right before `git commit -m`.](https://commitbrief.com/blog/review-before-the-push.md): 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.
- [LLM code review doesn't replace human review. It multiplies it.](https://commitbrief.com/blog/force-multiplier-manifesto.md): The position paper that ships with v1.0 — what an LLM catches, what it doesn't, and why a human reviewer's job changes shape rather than disappearing.

## FAQ

- [CommitBrief FAQ](https://commitbrief.com/faq.md): Every question and its full answer, in one markdown file.

Questions covered:

- Is my code sent to the LLM provider? What exactly leaves my machine?
- Is CommitBrief free? What license does it use?
- How much does a review cost?
- Can I run it fully offline?
- What is CommitBrief?
- Do I need an API key?
- Does CommitBrief write to my repo or change my code?
- Can I add my own secret patterns?
- Which provider should I pick?
- Does CommitBrief work with GitHub Actions or other CI?
- Which languages or file types does it review?
- Can a teammate hide a bug in the baseline?
- How do I silence flaky-test warnings?
- Does CommitBrief run on Windows?
- Can I narrow a review to specific files or directories?
- How do I stop seeing findings I've already triaged?
- How is this different from my editor's AI assistant?

## Optional

- [v1.16.0](https://commitbrief.com/changelog/v1.16.0.md): One flag. --timeout bounds a whole run and, crucially, raises the hard cap each provider used to enforce invisibly — the CLI tools' 5 minutes, ollama's 5, the Anthropic SDK's 10 — because a deadline alone can only cut a run short, never lengthen it.
- [v1.15.0](https://commitbrief.com/changelog/v1.15.0.md): Four new surfaces. commitbrief leaks audits the working tree and git history for committed credentials with no provider call; commitbrief map draws the commit graph and shows exactly what a filter selected; commit-level filters (--author, --committer, --start-date, --end-date, --text) review a set of commits instead of one diff; and commitbrief upgrade updates the binary across every install method.
- [v1.14.0](https://commitbrief.com/changelog/v1.14.0.md): Sandbox-rerun gets a runner. review.sandbox_command binds the executor seam that shipped inert in v1.12.0 — a list of argv elements, never a shell string, templated over the flagged test's file, line and name. Binding requires a double opt-in, and the MCP server and guard never run it.
- [v1.13.0](https://commitbrief.com/changelog/v1.13.0.md): Repair-oriented structured-output recovery. When a provider returns something that fails findings-JSON parsing, the pipeline no longer re-sends the byte-identical request — a lone markdown fence is now salvaged for free before parsing, and the single retry sends a failure-mode-specific repair prompt instead. Two new optional meta fields make retries and degrades visible.
- [v1.11.0](https://commitbrief.com/changelog/v1.11.0.md): Architecture-aware review. When a repo ships an `architecture.json` — the config of the sibling tool archlint, declaring layers and their allowed import edges — CommitBrief reads it and feeds a compact summary of the layers and their forbidden boundaries into the review prompt, so the reviewer can flag a diff that crosses a declared architectural boundary. A one-way read; CommitBrief never lints or enforces.
- [v1.12.0](https://commitbrief.com/changelog/v1.12.0.md): Sandbox-rerun confirmation for the flaky-test detector. The static rules infer flakiness from anti-patterns; sandbox-rerun raises confidence by re-running a flagged test in isolation N times and classifying it by the observed pass/fail mix — mixed confirms flaky, all-fail is a real failure, all-pass is transient (demoted to info). Opt-in and off by default, behind a runner seam that ships no language-specific runner yet.
- [v1.10.0](https://commitbrief.com/changelog/v1.10.0.md): A declarative merge gate — `commitbrief guard` — caps how many findings of each severity a change may carry via an opt-in `.commitbrief/policy.yml`. Richer than the single `--fail-on` threshold and aimed at gating high-volume, often AI-authored, pull requests. Run-mode reviews the diff; `--from-json` evaluates a review you already produced without a provider call.
- [v1.8.0](https://commitbrief.com/changelog/v1.8.0.md): Signal control to cut repeat noise — a user-private baseline that accepts a brownfield repo's existing findings so you only see new ones, and inline `// commitbrief-ignore` suppression with a visible reason — both true removals that are reported, never silent. Plus a `.pre-commit-hooks.yaml` for one-line pre-commit framework adoption, and three new flaky-test rules: brittle selectors, over-mocking, and wall-clock-dependent assertions.
- [v1.9.0](https://commitbrief.com/changelog/v1.9.0.md): An opt-in `commitbrief mcp` subcommand runs a Model Context Protocol server over stdio so an AI agent or host can call CommitBrief as a self-review gate before it submits code. It exposes one `review` tool that runs the exact same pipeline as `commitbrief --json` and returns the structured findings. Stdlib-only — no MCP SDK, no new dependency.
- [v1.7.0](https://commitbrief.com/changelog/v1.7.0.md): A deterministic flaky-test detector flags timing-dependent and unseeded-random anti-patterns in changed tests before any model call. Plus guard hardening — user-extensible secret patterns and a prompt-injection scan of your own rules — glob support for the `--file`/`--dir` filters, and a `setup --alias` installer for a `cbr` shell shortcut.
- [v1.6.0](https://commitbrief.com/changelog/v1.6.0.md): A new `summary` command explains a set of changes in plain language — a read-only digest grouped by logical area, attributed to commit hashes for a range. Plus `--lang` now drives the AI output language for any recognized language (French, German, …), independent of the CLI's own interface.
- [v1.5.0](https://commitbrief.com/changelog/v1.5.0.md): A new `commit` command turns a staged diff into a commit message and runs `git commit` for you, with `--type` formats and `--generate` alternatives. Plus `remote pr` no longer requests changes by default — the request-changes verdict is now opt-in.
- [v1.4.1](https://commitbrief.com/changelog/v1.4.1.md): A model-refresh release — OpenAI GPT-5 family support (including gpt-5.5-pro via the Responses API), the Gemini 3.x lineup, Claude Opus 4.8 as the new Anthropic default, and a setup wizard that no longer makes you retype an API key just to switch provider or model.
- [v1.2.1](https://commitbrief.com/changelog/v1.2.1.md): Inline PR comments land on the correct diff side, reviews send line-numbered diffs for sharper finding locations, and `remote pr` / `compress` / `providers test` gain the animated progress tree.
- [v1.3.0](https://commitbrief.com/changelog/v1.3.0.md): A fourth CLI-backed provider (`codex-cli`), `--with-context` for grounding CLI reviews in the wider repo, `remote pr --no-post` for local-only PR reviews, two new `cache` subcommands (`stats`, `inspect`) with size-bounded eviction, a `command.default` config key, and an SPDX-header CI guard.
- [v1.4.0](https://commitbrief.com/changelog/v1.4.0.md): A "Trust & quality" release — `--show-prompt` to see exactly what leaves your machine, an opt-in `guard.token_preflight`, a live elapsed-time counter on the progress spinner, the first published measured-quality benchmarks, and a fix for the spinner flooding the screen on some terminals.
- [v1.0.0](https://commitbrief.com/changelog/v1.0.0.md): API freeze. CLI surface, JSON schema v1, and rules formats are now under strict semver. `claude-cli` + `gemini-cli` promoted to stable.
- [v1.1.0](https://commitbrief.com/changelog/v1.1.0.md): Terminal-driven GitHub PR review lands — `commitbrief remote pr <ID>` fetches a PR's diff, posts inline review comments, and submits a verdict.
- [v1.2.0](https://commitbrief.com/changelog/v1.2.0.md): Three new providers (DeepSeek, Mistral, Cohere) bring the live count to 9, plus `--suggest-commit`, a `--min-severity` display filter, per-model pricing overrides, and a GitHub Action for CI.
- [v0.9.3](https://commitbrief.com/changelog/v0.9.3.md): CLI splash logo on every run — 16×16 half-block rendering of the CommitBrief mark, alongside wordmark and OSC 8 hyperlinks.
- [v0.9.2](https://commitbrief.com/changelog/v0.9.2.md): CLI provider polish — stdin transport for claude-cli, `compress --dry-run`, locale narrow to {en, tr}.
- [v0.9.1](https://commitbrief.com/changelog/v0.9.1.md): Safety scope narrowing — `--yes` no longer bypasses secret scanner or cost preflight.
- [v0.9.0](https://commitbrief.com/changelog/v0.9.0.md): CLI-as-provider (claude-cli, gemini-cli), `commitbrief diff` subcommand, per-finding suggestions, progress UI.
- [v0.8.1](https://commitbrief.com/changelog/v0.8.1.md): Finding card visual overhaul — per-severity themes, fixed-width panels, sign-aligned wrapping.
- [v0.8.0](https://commitbrief.com/changelog/v0.8.0.md): Quality & diagnostics. `doctor`, `install-hook`, secret scanner, cost preflight, `--fail-on`, `--compact`.
- [v0.7.0](https://commitbrief.com/changelog/v0.7.0.md): Multi-provider UX. `providers` and `config` subcommands; rich finding panel polish.
- [v0.6.0](https://commitbrief.com/changelog/v0.6.0.md): Structured findings JSON. OUTPUT.md becomes a Go template — breaking change.
- [v0.5.0](https://commitbrief.com/changelog/v0.5.0.md): Scope expansion. Every review scope advertised in `list` works end-to-end; JSON output locked at schema v1.
- [v0.4.0](https://commitbrief.com/changelog/v0.4.0.md): First public release. Homebrew, Scoop, and `go install` ship working.
- [v0.2.0](https://commitbrief.com/changelog/v0.2.0.md): Provider matrix — OpenAI, Gemini, and Ollama join Anthropic.
- [v0.1.0](https://commitbrief.com/changelog/v0.1.0.md): Walking-skeleton release — Anthropic provider, staged-diff review, cache.
- [License](https://commitbrief.com/legal/license.md): CommitBrief is GPL-3.0-or-later; dependencies are GPL-compatible.
- [Privacy](https://commitbrief.com/legal/privacy.md): CommitBrief has no telemetry. The website logs aggregate analytics only.
- [Terms of use](https://commitbrief.com/legal/terms.md): Use of CommitBrief and this website is governed by the GPL-3.0 license terms.