Install
// docs · v1.0

Run your first review

Three commands from a fresh CommitBrief install to your first structured code review on staged changes.

Three steps from a fresh install to your first review.

1. Configure a provider

commitbrief setup

The interactive wizard asks for:

  • Provider — Anthropic, OpenAI, Gemini, or Ollama.
  • API key — for Anthropic / OpenAI / Gemini. Ollama needs no key but asks for a base URL (default http://localhost:11434).
  • Model — picked from the provider’s static list. For Ollama, the wizard queries <base_url>/api/tags and lists models you have pulled locally.
  • Connection test — a fast ping against the chosen provider with the credentials you entered. A failure aborts the wizard.

On success, the configuration is written to ~/.commitbrief/config.yml (mode 0600). Pass --local to write the repo-local <repo>/.commitbrief/config.yml instead — useful when one repo needs different credentials. The repo-local path is added to .gitignore automatically.

See Providers for which one to pick.

2. (Optional) Scaffold project rules

commitbrief init

Writes two files in the current repo:

  • COMMITBRIEF.md at the repo root — team-shared review rules, perspectives, project context. Sent to the LLM as the system prompt. Commit this to git.
  • .commitbrief/OUTPUT.md — per-user Go text/template controlling how findings are formatted locally (used by --markdown / --output <file>.md). Gitignored by default.

Both files fall back to embedded defaults at runtime, so skipping this step is fine for a first try. See Review rules for the file formats.

3. Review changes

Stage some changes, then:

commitbrief --staged

Equivalent forms for other scopes:

commitbrief                          # = --staged (default)
commitbrief --unstaged               # working-tree changes
commitbrief diff HEAD                # working tree vs HEAD
commitbrief diff HEAD~3 HEAD         # the last three commits
commitbrief diff main feature        # one branch vs another
commitbrief diff main...feature      # three-dot range (PR style)

Narrow any scope with repeatable path filters:

commitbrief --staged --file src/main.go --file src/util.go
commitbrief --unstaged --dir database/seeder
commitbrief diff HEAD~3 HEAD --dir docs

See Review scopes for the full breakdown.

What you see

A typical review prints in this order:

  1. The splash logo (stderr, TTY only).
  2. Per-stage progress: searching → diff stats → preparing → thinking.
  3. Severity-coded panel per finding (lipgloss header / status / footer).
  4. An optional verbose footer with provider / model / tokens / cost / latency when --verbose (-v) is set.

Use --json for machine output, --markdown for plain markdown (no ANSI), --output <file> to redirect, or --copy to push the findings to the system clipboard via OSC 52. See Output formats.

Verify the pipeline

commitbrief doctor

Runs eight checks against the resolved environment: git on PATH, config schema, COMMITBRIEF.md source, OUTPUT.md template, configured provider, active provider has credentials, cache directory writable, repo .gitignore includes .commitbrief/. Exits non-zero on any fail — safe to wire into CI as a config gate. See Troubleshooting for what each row means.

Next steps