# 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 docs · v1.x · Configuration

Canonical URL: https://commitbrief.com/docs/1.x/providers

---

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](#openai-compatible-deepseek-mistral-cohere) below.

## Picking and switching

```sh
# 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

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

Get a key from [console.anthropic.com](https://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

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

Get a key from [platform.openai.com](https://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

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

Get a key from [aistudio.google.com](https://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` |

```yaml
provider: deepseek          # or mistral / cohere
providers:
  deepseek:
    api_key: sk-...
    model: deepseek-chat
```

```sh
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>`](/docs/1.x/configuration#per-model-pricing-override)
when the snapshot drifts.

## Ollama (local)

```yaml
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](https://ollama.com/download) 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](https://www.anthropic.com/claude-code) (`claude`),
[Gemini CLI](https://ai.google.dev/gemini-api/docs/cli) (`gemini`),
or [OpenAI Codex CLI](https://openai.com/codex/) (`codex`). No HTTPS
calls from CommitBrief — your existing subscription handles auth and
billing.

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

```sh
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.

```sh
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 |

## See also

- [Configuration](/docs/1.x/configuration) — the YAML schema in
  full.
- [Safety and cost](/docs/1.x/safety-and-cost#cost-preflight) —
  how per-provider pricing feeds the preflight check.
- [Troubleshooting](/docs/1.x/troubleshooting) — `commitbrief
  doctor` includes a per-provider connection ping.