Quick start

Quick start

Three steps from a fresh install to your first review.

1. Configure a provider

commitbrief setup

The interactive wizard asks you to pick a provider (Anthropic, OpenAI, Gemini, or Ollama), paste an API key (skipped for Ollama), pick a model, and runs a connectivity test. On success, the configuration is written to ~/.commitbrief/config.yml. Pass --local to write the repo-local .commitbrief/config.yml instead — useful when one repo needs different credentials.

See Setup command for details, including how to inject the API key via an environment variable instead of typing it.

2. (Optional) Write project review 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 Init command and COMMITBRIEF.md / OUTPUT.md 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 command, diff, and Filtering.

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. Cards-rendered findings (lipgloss header/status/footer with severity-coded panels).
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.

Next steps

• Install a git hook: commitbrief install-hook (see Install-hook command).
• Verify your pipeline: commitbrief doctor (see Doctor command).
• Inspect the pipeline without spending tokens: commitbrief dry-run --staged (see Dry-run command).
• Pick a different default provider: commitbrief providers use openai (see Providers command).