Getting started

CommitBrief is a single-binary CLI that runs an LLM-powered code review against a git diff. It is local-first, provider-agnostic, and deterministic enough to wire into a pre-commit hook or a CI gate.

Who it’s for

Developers and engineers who want a structured, opinionated second opinion on a diff before it leaves their machine — or on a PR before a human reviewer touches it. The output is structured findings (severity, file, line, title, description, suggestion), not a vague summary. The same surface drives the colored terminal cards, the JSON-piped CI gate, and the markdown that lands in a PR comment.

What ships in the binary

• Six provider backends. Anthropic, OpenAI, Google Gemini, Ollama (local), plus subprocess wrappers around the Claude Code CLI and the Gemini CLI. One CommitBrief install, pick whichever fits your billing model.
• Three review scopes. --staged and --unstaged for the working tree; commitbrief diff <args> for any historic range git diff understands (HEAD~3, main...feature, merge commits).
• Three output formats. Lipgloss-styled cards for TTY, JSON schema v1 for tooling, markdown (driven by a Go template) for files and PR bodies.
• Pre-send guards. A secret scanner blocks credential-shaped strings before any provider call; a cost preflight refuses to spend more than cost.warn_threshold_usd without a prompt.
• Local response cache. SHA-256 over the diff + system prompt + provider + model + locale; cached entries cost nothing on replay. See cache management.
• --fail-on=<severity> CI gate. Maps the highest finding severity to exit 1. Wire into pre-commit / pre-push / GitHub Actions.

Local-first by design

Nothing about CommitBrief leaves your machine without your consent:

• API keys live in ~/.commitbrief/config.yml (mode 0600) or the repo-local <repo>/.commitbrief/config.yml (gitignored automatically).
• Diffs go directly from your git repo to the configured provider over HTTPS. CommitBrief does not run a backend service, does not collect telemetry, and does not phone home.
• The review rules in COMMITBRIEF.md are shipped as the system prompt verbatim — wrapped in an XML envelope with a prompt-injection guard, but otherwise untouched.

Next steps

• Install the binary — Homebrew, Scoop, go install, or pre-built archives.
• Run your first review — three commands from a fresh install to your first set of findings.
• Pick a provider — comparison of the four API providers plus the two CLI-tool-backed providers.
• Wire it into git hooks — pre-commit, commit-msg, or pre-push.

License and source

CommitBrief is GPL-3.0-or-later. Source, issue tracker, and release notes live at github.com/CommitBrief/commitbrief. The wiki at github.com/CommitBrief/commitbrief/wiki is the deeper reference — every command, flag, and configuration key is documented page-per-topic, verified against the binary source.