Providers
Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Cohere, any OpenAI-compatible endpoint, Ollama, claude-cli, gemini-cli, codex-cli — when to pick which, plus per-provider config and pricing.
CommitBrief supports eleven review backends. Eight call HTTPS APIs
directly; three shell out to a host CLI tool. One additional mock
provider is registered for tests and not user-relevant.
At a glance
| Name | Kind | Default model | API key env |
|---|---|---|---|
anthropic | api | claude-opus-5-5 | ANTHROPIC_API_KEY |
claude-cli | cli | — | — |
codex-cli | cli | — | — |
cohere | api | command-r-plus | COHERE_API_KEY |
deepseek | api | deepseek-chat | DEEPSEEK_API_KEY |
gemini | api | gemini-3.8-flash | GEMINI_API_KEY |
gemini-cli | cli | — | — |
mistral | api | mistral-large-latest | MISTRAL_API_KEY |
ollama | local | qwen2.5-coder:14b | — |
openai | api | gpt-5.4-mini | OPENAI_API_KEY |
openai-compatible | api | — | — |
Which one?
anthropic— Claude models; ephemeral prompt cache. The default is marked in the model table.openai— strict structured-output JSON mode; automatic prompt caching at ≥1024 tokens.gemini— a 1M-token context on every model; Flash models keep per-review cost low.deepseek— low-cost reviews;deepseek-reasonerfor deeper analysis.mistral— European hosting;codestral-latestis code-tuned.cohere—command-a/command-rfamily via the compatibility endpoint.openai-compatible— any endpoint that speaks the OpenAI Chat Completions protocol (vLLM, LM Studio, LiteLLM, a corporate gateway); you supply the URL and model. Requires v1.19.0 or later.ollama— air-gapped or zero-cost reviews; you supply the GPU/CPU.claude-cli— reuse your Claude Code subscription; no second API key.gemini-cli— reuse your Gemini CLI auth.codex-cli— reuse your OpenAI Codex CLI auth.
DeepSeek, Mistral, and Cohere speak the OpenAI Chat Completions
protocol, so CommitBrief drives them through the same openai-go
SDK pointed at a different base URL — no extra dependency. See
OpenAI-compatible below.
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-3.1-flash-lite --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-5-5
Get a key from console.anthropic.com. Env override:
ANTHROPIC_API_KEY.
| Model | Default? | Context | Input / Output / Cached (per 1M tokens) |
|---|---|---|---|
claude-opus-4-8 | — | 1M | $5.00 / $25.00 / $0.50 |
claude-sonnet-4-6 | — | 1M | $3.00 / $15.00 / $0.30 |
claude-haiku-4-5-20251001 | — | 200K | $1.00 / $5.00 / $0.10 |
claude-opus-5-5 | ✓ | 1M | $4.00 / $20.00 / $0.20 |
claude-sonnet-5 | — | 1M | $2.00 / $10.00 / $0.20 |
claude-fable-5-1 | — | 1M | $10.00 / $50.00 / $0.25 |
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-5.4-mini
Get a key from platform.openai.com. Env override:
OPENAI_API_KEY.
| Model | Default? | Context | Input / Output / Cached (per 1M tokens) |
|---|---|---|---|
gpt-5.4-mini | ✓ | 400K | $0.75 / $4.50 / $0.075 |
gpt-5.5 | — | 1.05M | $5.00 / $30.00 / $0.50 |
gpt-5.5-pro | — | 1.05M | $30.00 / $180.00 / = $30.00 |
gpt-6-astra | — | 1.05M | $10.00 / $50.00 / $1.00 |
gpt-6-sol | — | 1.05M | $2.00 / $10.00 / $0.20 |
gpt-6-luna | — | 1.05M | $0.10 / $0.50 / $0.01 |
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-3.8-flash
Get a key from aistudio.google.com. Env override:
GEMINI_API_KEY.
| Model | Default? | Context | Input / Output / Cached (per 1M tokens) |
|---|---|---|---|
gemini-3.1-pro-preview | — | 1M | $2.00 / $12.00 / $0.20 |
gemini-3.5-flash | — | 1M | $1.50 / $9.00 / $0.15 |
gemini-3.1-flash-lite | — | 1M | $0.25 / $1.50 / $0.025 |
gemini-3.8-flash | ✓ | 1M | $0.75 / $3.75 / $0.075 |
gemini-3.5-flash-lite | — | 1M | $0.30 / $2.50 / $0.03 |
Every Gemini model takes a 1M-token context — 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, 65536], the Gemini 3 output limit, so a
malformed or oversized config never reaches the API. The default is 16384 for the thinking models
(their thought tokens share the budget) and 4096 for the Lite models;
thought tokens count as output tokens in cost figures. If a response
comes back empty at the token limit, the limit is doubled and the call
retried once; both calls’ usage is added to the cost.
OpenAI-compatible (DeepSeek, Mistral, Cohere)
deepseek, mistral, and cohere talk to OpenAI-compatible Chat
Completions endpoints, so CommitBrief reuses the openai-go SDK
pointed at each provider’s base URL. No extra dependency is
pulled in for them.
| Provider | Default base URL | API key env | Default model | Other models |
|---|---|---|---|---|
deepseek | https://api.deepseek.com | DEEPSEEK_API_KEY | deepseek-chat | deepseek-reasoner |
mistral | https://api.mistral.ai/v1 | MISTRAL_API_KEY | mistral-large-latest | mistral-small-latest, codestral-latest |
cohere | https://api.cohere.ai/compatibility/v1 | COHERE_API_KEY | command-r-plus | command-r, command-a-03-2025 |
provider: deepseek # or mistral / cohere
providers:
deepseek:
api_key: sk-...
model: deepseek-chat
commitbrief setup # pick DeepSeek / Mistral / Cohere + key
commitbrief providers use deepseek # switch later
commitbrief --provider mistral --staged
The API key comes from config (providers.<name>.api_key) or the
matching environment variable above.
Structured output. Unlike the native OpenAI provider, these do
not send a response_format JSON-schema directive — their
strict-JSON support varies by provider and model. The findings
shape comes from the system prompt’s contract, and the
retry-once-then-degrade pipeline handles output that doesn’t parse,
exactly the way Ollama does. Capable models follow the prompt;
smaller ones may degrade to plain text.
Pricing. Per-1M-token rates are hard-coded snapshots shown in
the --verbose footer. No automatic prompt-cache discount is
assumed for Mistral/Cohere; DeepSeek’s cache-hit rate may not be
reported through the compatibility usage payload. Override any rate
with providers.<name>.pricing.<model>
when the snapshot drifts.
Shared options for API providers
Requires v1.19.0 or later.
| Key | Meaning |
|---|---|
providers.<name>.api_key_env | Name of an environment variable that holds the key. Beats the provider’s fixed variable (ANTHROPIC_API_KEY and so on) and api_key. A variable that is set but empty is an error, not a fallthrough. Inert for the *-cli providers. |
providers.<name>.context_window | Token window used by the pre-send preflight. Overrides the built-in value for the model. |
deepseek, mistral and cohere no longer send OPENAI_ORG_ID and
OPENAI_PROJECT_ID as request headers. Older versions did if
those variables were set, which sent an OpenAI identifier to a
different vendor.
The openai-compatible provider
Requires v1.19.0 or later. For any endpoint that speaks Chat Completions and is not one of the three above. Nothing is assumed about it, so you declare what CommitBrief cannot know.
provider: openai-compatible
providers:
openai-compatible:
base_url: http://localhost:8000/v1
model: qwen2.5-coder-32b-instruct
api_key_env: LOCAL_LLM_KEY # optional
context_window: 32768 # optional, enables the token preflight
pricing:
qwen2.5-coder-32b-instruct:
input_per_1m: 0.40 # USD; optional
output_per_1m: 1.20
| Setting | Behavior |
|---|---|
base_url, model | Required. base_url must be http or https and have a host. providers use openai-compatible prints a hint when either is missing. |
| API key | Optional. Order: api_key_env, then api_key, then no Authorization header at all. |
| Structured output | No response_format is sent. The findings shape comes from the prompt, with fence salvage and a repair retry, as for Ollama. Weaker models may degrade to plain text. |
| Headers | OpenAI-Organization and OpenAI-Project are never sent. |
| Pricing | Taken from pricing.<model>. With no price, cost shows as unknown, one stderr note is printed, and the cost confirmation is skipped. A price of 0.0 counts as not declared. |
| Context window | Taken from context_window. Without it the token preflight is skipped, with a note. |
| Plain HTTP | http:// to a host that is not loopback prints a one-line stderr warning, also under --quiet. It is a warning, not a refusal. |
commitbrief doctor fails when api_key_env names an empty
variable. A --dry-run shows Cost estimate: unknown when no price
is declared.
What it cannot promise. Structured-output quality is whatever the server and model deliver. CommitBrief cannot tell a local 7B model from a frontier one, and the verbose footer’s cost is only as right as the price you wrote down.
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:14betc.). - The configured
base_urlreachable from the machine runningcommitbrief. Defaulthttp://localhost:11434is 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, gemini-cli, and codex-cli
Subprocess wrappers around the user’s locally-installed
Claude Code (claude),
Gemini CLI (gemini),
or OpenAI Codex CLI (codex). No HTTPS
calls from CommitBrief — your existing subscription handles auth and
billing.
provider: claude-cli # or gemini-cli / codex-cli
providers:
claude-cli:
model: "" # ignored — host CLI manages selection
gemini-cli:
model: ""
codex-cli:
model: ""
commitbrief --cli claude --staged
commitbrief --cli gemini --staged
commitbrief --cli codex --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 the platform command-line size (~120 KB for the prompt). An oversized prompt is rejected before gemini starts, with the size, the limit and how to shrink it. |
codex-cli | codex (OpenAI Codex CLI) | argv (codex exec --sandbox read-only --skip-git-repo-check <prompt>). |
For huge diffs, narrow the review with --file / --dir, or prefer claude-cli or one of the API providers.
Codex is an agentic CLI, so CommitBrief drives it through its
non-interactive codex exec subcommand pinned to a
--sandbox read-only mode — a review can never modify your working
tree. Its final message streams back verbatim like the other CLI
providers.
Limitations
- No structured findings → no severity gating, no
--fail-on, no--copyof findings. --json/--markdownare mutually exclusive with--cliat the cobra level.--sarifis refused as well, before any call, because SARIF needs structured findings.- The cost preflight short-circuits (zero pricing); the verbose
footer shows
—for the dollar amount.
Grounding the review in your repo — --with-context
By default a review sees only the diff. Pass --with-context and the
agentic host CLI may read other files in the repository — callers
of the changed code, type and interface definitions, sibling modules,
your project’s own conventions — to ground its review in how the change
fits the wider codebase. The diff stays the subject of the review; the
rest is background.
commitbrief --cli claude --staged --with-context
commitbrief --cli codex --unstaged --with-context
- CLI providers only. An API provider has no filesystem, so the
flag errors there and points you at
--cli. - Read-only. The host CLI runs with its working directory pinned to
the repo root and only read tools enabled
(
claude --allowedTools Read,Grep,Glob,gemini --approval-mode plan --skip-trust;codex’s read-only sandbox already permits reads). Write and network-mutation capabilities are never granted. - Distinct cache key. A
--with-contextrun and a diff-only run on the same diff are cached separately, so they never replay each other.
⚠ Security boundary. With
--with-contextthe agent decides which files to open, so file contents beyond the diff — including untracked secrets (.env, key files) and.commitbrief/config — can reach the host CLI’s backend. The pre-send secret scanner and the.commitbrief/**guard cover the diff only, not files the agent reads on its own. CommitBrief prints a one-line caution on every--with-contextrun; the flag itself is your consent. Use it on repositories you trust.
Provider vs binary cheatsheet
| Provider | Binary on PATH | API endpoint |
|---|---|---|
anthropic | — | api.anthropic.com |
openai | — | api.openai.com |
gemini | — | generativelanguage.googleapis.com |
deepseek | — | api.deepseek.com |
mistral | — | api.mistral.ai/v1 |
cohere | — | api.cohere.ai/compatibility/v1 |
openai-compatible | — | <base_url> |
ollama | ollama daemon at base_url | <base_url> |
claude-cli | claude | (subprocess) |
gemini-cli | gemini | (subprocess) |
codex-cli | codex | (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 |
--sarif | Available | Refused |
| Per-call cost | Billed via the provider | Counts against your host CLI subscription |
See also
- Configuration — the YAML schema in full.
- Safety and cost — how per-provider pricing feeds the preflight check.
- Troubleshooting —
commitbrief doctorincludes a per-provider connection ping.