# Getting started

> What CommitBrief is, who it's for, and how the local LLM review pipeline fits into a developer's workflow.

CommitBrief docs · v1.x · Getting Started

Canonical URL: https://commitbrief.com/docs/1.x/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

- **Ten provider backends.** Anthropic, OpenAI, Google Gemini,
  the OpenAI-compatible trio
  [DeepSeek, Mistral, and Cohere](/docs/1.x/providers#openai-compatible-deepseek-mistral-cohere),
  Ollama (local), plus subprocess wrappers around the
  [Claude Code, Gemini, and OpenAI Codex CLIs](/docs/1.x/providers#claude-cli-gemini-cli-and-codex-cli).
  One CommitBrief install, pick whichever fits your billing model.
- **Four review scopes — plus GitHub PRs.** `--staged` and
  `--unstaged` for the working tree; `commitbrief diff <args>` for
  any historic range `git diff` understands (HEAD~3,
  `main...feature`, merge commits);
  [commit filters](/docs/1.x/review-scopes#commit-filters-v1150)
  (`--author`, `--start-date`, `--text`, …) to review a *set of
  commits* selected from anywhere in the history; and
  [`commitbrief remote pr <ID>`](/docs/1.x/remote-pr) to review a
  pull request and post findings back to GitHub as inline comments.
- **Three output formats.** Lipgloss-styled
  [cards](/docs/1.x/output-formats#cards-default-tty) for TTY,
  [JSON schema v1](/docs/1.x/output-formats#json-schema-v1) for
  tooling, [markdown](/docs/1.x/output-formats#markdown) (driven
  by a Go template) for files and PR bodies.
- **Pre-send guards.** A
  [secret scanner](/docs/1.x/safety-and-cost#secret-scanner) blocks
  credential-shaped strings before any provider call; a
  [cost preflight](/docs/1.x/safety-and-cost#cost-preflight)
  refuses to spend more than `cost.warn_threshold_usd` without a
  prompt.
- **Two deterministic commands that never call a model.**
  [`commitbrief leaks`](/docs/1.x/leaks) audits your whole tree and
  git history for committed credentials;
  [`commitbrief map`](/docs/1.x/commit-graph) draws the commit
  graph so you can see what a filter selected before paying for a
  review. No provider, no cache, no cost.
- **Local response cache.** SHA-256 over the diff + system prompt +
  provider + model + locale; cached entries cost nothing on replay.
  See [cache management](/docs/1.x/safety-and-cost#cache).
- **`--fail-on=<severity>` CI gate.** Maps the highest finding
  severity to exit 1. Wire into pre-commit / pre-push, or run the
  official [GitHub Action](/docs/1.x/severity#the-official-github-action).
- **`--suggest-commit`.** After a staged review, makes a second
  free-form call and prints a single Conventional Commit message to
  stdout — read-only, it never writes git. See
  [Suggesting commit messages](/docs/1.x/output-formats#suggesting-a-commit-message).

## 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`](/docs/1.x/review-rules)
  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](/docs/1.x/installation)** — Homebrew,
  Scoop, `go install`, or pre-built archives.
- **[Run your first review](/docs/1.x/first-review)** — three
  commands from a fresh install to your first set of findings.
- **[Pick a provider](/docs/1.x/providers)** — comparison of the
  seven API providers plus the three CLI-tool-backed providers.
- **[Wire it into git hooks](/docs/1.x/git-hooks)** — `pre-commit`,
  `commit-msg`, or `pre-push`.
- **[Review pull requests](/docs/1.x/remote-pr)** — `commitbrief
  remote pr` and the GitHub Action.

## License and source

CommitBrief is **GPL-3.0-or-later**. Source, issue tracker, and
release notes live at
[github.com/CommitBrief/commitbrief](https://github.com/CommitBrief/commitbrief).
The wiki at
[github.com/CommitBrief/commitbrief/wiki](https://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.