// docs · v1.x

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.

Updated October 18, 2026

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

NameKindDefault modelAPI key env
anthropicapiclaude-opus-5-5ANTHROPIC_API_KEY
claude-clicli——
codex-clicli——
cohereapicommand-r-plusCOHERE_API_KEY
deepseekapideepseek-chatDEEPSEEK_API_KEY
geminiapigemini-3.8-flashGEMINI_API_KEY
gemini-clicli——
mistralapimistral-large-latestMISTRAL_API_KEY
ollamalocalqwen2.5-coder:14b—
openaiapigpt-5.4-miniOPENAI_API_KEY
openai-compatibleapi——

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-reasoner for deeper analysis.
  • mistral — European hosting; codestral-latest is code-tuned.
  • cohere — command-a / command-r family 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.

ModelDefault?ContextInput / 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.

ModelDefault?ContextInput / 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.

ModelDefault?ContextInput / 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.

ProviderDefault base URLAPI key envDefault modelOther models
deepseekhttps://api.deepseek.comDEEPSEEK_API_KEYdeepseek-chatdeepseek-reasoner
mistralhttps://api.mistral.ai/v1MISTRAL_API_KEYmistral-large-latestmistral-small-latest, codestral-latest
coherehttps://api.cohere.ai/compatibility/v1COHERE_API_KEYcommand-r-pluscommand-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.

KeyMeaning
providers.<name>.api_key_envName 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_windowToken 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
SettingBehavior
base_url, modelRequired. base_url must be http or https and have a host. providers use openai-compatible prints a hint when either is missing.
API keyOptional. Order: api_key_env, then api_key, then no Authorization header at all.
Structured outputNo 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.
HeadersOpenAI-Organization and OpenAI-Project are never sent.
PricingTaken 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 windowTaken from context_window. Without it the token preflight is skipped, with a note.
Plain HTTPhttp:// 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: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

ProviderExpected on PATHPrompt transport
claude-cliclaude (Claude Code)stdin (claude -p -) — no ARG_MAX ceiling.
gemini-cligemini (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-clicodex (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 --copy of findings.
  • --json / --markdown are mutually exclusive with --cli at the cobra level. --sarif is 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-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

ProviderBinary on PATHAPI 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>
ollamaollama daemon at base_url<base_url>
claude-cliclaude(subprocess)
gemini-cligemini(subprocess)
codex-clicodex(subprocess)

Picking between API providers vs CLI providers

PropertyAPI providersCLI-tool providers
AuthAPI key in CommitBrief configHost CLI’s own auth
Output shapeStructured findings JSON (schema v1)Pre-formatted plain text
Cards / JSON / Markdown renderingAll three availablePlain-text emit only
--fail-on severity gateHonoredNot applicable
--sarifAvailableRefused
Per-call costBilled via the providerCounts against your host CLI subscription

See also