// docs · v1.0

Providers

Anthropic, OpenAI, Gemini, Ollama, claude-cli, gemini-cli — when to pick which, plus per-provider config and pricing.

CommitBrief supports six review backends. Four call HTTPS APIs directly; two shell out to a host CLI tool. One additional mock provider is registered for tests and not user-relevant.

At a glance

Name	Type	API key	Best for
`anthropic`	HTTPS API	required	Highest review quality with `claude-opus-4-7`; ephemeral prompt cache.
`openai`	HTTPS API	required	Strict structured-output JSON mode; automatic prompt caching at ≥1024 tokens.
`gemini`	HTTPS API	required	Largest context windows (`gemini-2.5-pro`: 2M tokens).
`ollama`	HTTPS API (local)	not needed	Air-gapped or zero-cost reviews; you supply the GPU/CPU.
`claude-cli`	host-CLI subprocess	not needed	Reuse your Claude Code subscription; no second API key.
`gemini-cli`	host-CLI subprocess	not needed	Reuse your Gemini CLI auth.

Picking and switching

# Interactive wizard (asks which one + API key + model).
commitbrief setup

# Switch the active default later without re-entering keys.
commitbrief providers use openai

# Override for one invocation.
commitbrief --provider gemini --model gemini-2.5-flash --staged

# Shorthand for the CLI-tool-backed providers.
commitbrief --cli claude --staged

# Test connectivity without modifying state.
commitbrief providers test gemini

Anthropic

provider: anthropic
providers:
  anthropic:
    api_key: sk-ant-...
    model: claude-opus-4-7

Get a key from console.anthropic.com. Env override: ANTHROPIC_API_KEY.

Model	Default?	Context	Input / Output / Cached (per 1M tokens)
`claude-opus-4-7`	✓	200K	$15.00 / $75.00 / $1.50
`claude-sonnet-4-6`	—	200K	$3.00 / $15.00 / $0.30
`claude-haiku-4-5-20251001`	—	200K	$1.00 / $5.00 / $0.10

Uses Anthropic’s ephemeral prompt-caching (5-minute TTL) — the system-prompt section is marked for caching, cutting repeated-input cost ~10× when you re-run reviews against a similar diff.

Structured findings via the tools API; one retry on malformed JSON, then graceful degrade to markdown.

OpenAI

provider: openai
providers:
  openai:
    api_key: sk-...
    model: gpt-4o

Get a key from platform.openai.com. Env override: OPENAI_API_KEY.

Model	Default?	Context	Input / Output / Cached (per 1M tokens)
`gpt-4o`	✓	128K	$2.50 / $10.00 / $1.25
`gpt-4o-mini`	—	128K	$0.15 / $0.60 / $0.075

OpenAI’s strict JSON mode rejects optional properties, so the required-vs-optional split is enforced at the provider boundary: severity, file, line, title, description, and suggestion are required; line_end, language, snippet are optional and prompt-driven.

Automatic prompt caching applies at ≥1024-token repeated prefixes; cached tokens show in the verbose footer.

Google Gemini

provider: gemini
providers:
  gemini:
    api_key: AIza...
    model: gemini-2.5-pro

Get a key from aistudio.google.com. Env override: GEMINI_API_KEY.

Model	Default?	Context	Input / Output / Cached (per 1M tokens)
`gemini-2.5-pro`	✓	2M	$1.25 / $10.00 / $0.31
`gemini-2.5-flash`	—	1M	$0.30 / $2.50 / $0.075
`gemini-1.5-flash`	—	1M	$0.075 / $0.30 / $0.01875

Gemini has the largest free-tier context windows of any supported provider — useful for reviews of very large diffs that would not fit elsewhere.

Structured findings via ResponseSchema. The max-output-tokens request is bounded to [1, math.MaxInt32] (4096 default) so a malformed config never wraps to a negative value.

Ollama (local)

provider: ollama
providers:
  ollama:
    base_url: http://localhost:11434
    model: qwen2.5-coder:14b

No API key. Env override for the base URL: OLLAMA_HOST.

Requirements

Ollama installed and running.
At least one model pulled (ollama pull qwen2.5-coder:14b etc.).
The configured base_url reachable from the machine running commitbrief. Default http://localhost:11434 is the typical local install.

The setup wizard queries <base_url>/api/tags to list models you have pulled and offers them as a pick-list. If discovery fails, the wizard falls back to free-text input.

Pricing: provider.Pricing{} — all zero. The cost preflight short-circuits silently; the verbose footer shows — for the dollar figure. Token counts are still reported.

Reliability: small instruct models may produce malformed JSON more often than the API providers; the retry-once-then-degrade fallback handles it.

`claude-cli` and `gemini-cli`

Subprocess wrappers around the user’s locally-installed Claude Code (claude) or Gemini CLI (gemini). No HTTPS calls from CommitBrief — your existing subscription handles auth and billing.

provider: claude-cli      # or gemini-cli
providers:
  claude-cli:
    model: ""             # ignored — host CLI manages selection
  gemini-cli:
    model: ""

commitbrief --cli claude --staged
commitbrief --cli gemini --staged

Binary expectations

Provider	Expected on PATH	Prompt transport
`claude-cli`	`claude` (Claude Code)	stdin (`claude -p -`) — no ARG_MAX ceiling.
`gemini-cli`	`gemini` (Gemini CLI)	argv (`-p <prompt>`) — limited by platform `ARG_MAX` (~128 KB).

For huge diffs, prefer claude-cli or one of the API providers.

Limitations

No structured findings → no severity gating, no --fail-on, no --copy of findings.
--json / --markdown are mutually exclusive with --cli at the cobra level.
The cost preflight short-circuits (zero pricing); the verbose footer shows — for the dollar amount.

Provider vs binary cheatsheet

Provider	Binary on PATH	API endpoint
`anthropic`	—	`api.anthropic.com`
`openai`	—	`api.openai.com`
`gemini`	—	`generativelanguage.googleapis.com`
`ollama`	`ollama` daemon at `base_url`	`<base_url>`
`claude-cli`	`claude`	(subprocess)
`gemini-cli`	`gemini`	(subprocess)

Picking between API providers vs CLI providers

Property	API providers	CLI-tool providers
Auth	API key in CommitBrief config	Host CLI’s own auth
Output shape	Structured findings JSON (schema v1)	Pre-formatted plain text
Cards / JSON / Markdown rendering	All three available	Plain-text emit only
`--fail-on` severity gate	Honored	Not applicable
Per-call cost	Billed via the provider	Counts against your host CLI subscription