// docs · v1.x

Providers

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

CommitBrief supports ten review backends. Seven 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	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).
`deepseek`	HTTPS API (OpenAI-compatible)	required	Low-cost reviews; `deepseek-reasoner` for deeper analysis.
`mistral`	HTTPS API (OpenAI-compatible)	required	European hosting; `codestral-latest` is code-tuned.
`cohere`	HTTPS API (OpenAI-compatible)	required	`command-a` / `command-r` family via the compatibility endpoint.
`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.
`codex-cli`	host-CLI subprocess	not needed	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-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.

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.

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`, `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 platform `ARG_MAX` (~128 KB).
`codex-cli`	`codex` (OpenAI Codex CLI)	argv (`codex exec --sandbox read-only --skip-git-repo-check <prompt>`).

For huge diffs, 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 --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.

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-context run and a diff-only run on the same diff are cached separately, so they never replay each other.

⚠ Security boundary. With --with-context the 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-context run; 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`
`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
Per-call cost	Billed via the provider	Counts against your host CLI subscription