Provider CLI tools

Home / Providers / CLI tools

Provider: claude-cli, gemini-cli, and codex-cli

CLI-tool-backed providers reuse the user's locally-installed Claude Code (claude), Gemini CLI (gemini), or Codex CLI (codex) as the review backend. CommitBrief invokes the binary as a subprocess and streams its stdout back to the user. No HTTPS calls from CommitBrief itself — your existing subscription handles auth and billing.

The review block is bracketed at the top and bottom with a -------------------- rule — the same 20-hyphen separator the prompt uses between findings — so the whole block reads as one fenced unit when pasted into chat or piped to a file. The edge rules are added by CommitBrief; findings in the middle are separated by the model.

When to use

• You already have a Claude Code or Gemini CLI subscription and want to avoid managing a second API key.
• You want to pay through your existing subscription instead of per-token API costs.
• You are happy with the host CLI's response shape (markdown-ish prose) and do not need structured findings.

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 — passing both is rejected upfront (UC-07).
• --output <file> works since v0.9.2 (UC-07): the plain-text emit path now routes through the same openOutput helper the structured renderers use.
• The cost preflight short-circuits (zero pricing). The cost.warn_threshold_usd config field has no effect.

Configuration

provider: claude-cli      # or gemini-cli / codex-cli
providers:
  claude-cli:
    model: ""             # ignored — Claude Code manages its own selection
  gemini-cli:
    model: ""
  codex-cli:
    model: ""

No API key field is needed; the host CLI manages auth.

Invoking

The dedicated shorthand:

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

Equivalent to:

commitbrief --provider claude-cli --staged
commitbrief --provider gemini-cli --staged
commitbrief --provider codex-cli --staged

Binary detection

• claude-cli → expects claude on PATH (Anthropic's Claude Code).
• gemini-cli → expects gemini on PATH (Google's Gemini CLI).
• codex-cli → expects codex on PATH (OpenAI's Codex CLI).

commitbrief doctor runs a per-provider connection ping that includes resolving the binary path and invoking <binary> --version. A missing binary surfaces as a Warn in the doctor table.

Invocation shape

Both providers wrap a single Spec from the clireview package:

Field	Anthropic (claude-cli)	Gemini (gemini-cli)	OpenAI (codex-cli)
Binary	claude	gemini	codex
Prompt transport	stdin (-p -) — UC-24 since v0.9.2	argv (-p <prompt>)	argv (exec <prompt>)
Response format	--output-format text	(default plain text)	exec --sandbox read-only --skip-git-repo-check (headless, read-only)
Version probe	claude --version	gemini --version	codex --version
Per-call timeout	5 minutes	5 minutes	5 minutes

codex-cli note: Codex is an agentic CLI, so it is driven via its non-interactive codex exec subcommand with a --sandbox read-only pin — a review must never let it modify the working tree. Its final message streams through verbatim like the other CLI providers. The exact exec flags are validated against a live codex binary under make test-live; if your Codex CLI version differs, the one-shot invocation lives in internal/provider/codex-cli/codex_cli.go.

The combined system+user prompt is built the same way as for API providers (system message wraps <project_rules> XML, user message contains the diff). The two halves are joined with \n\n and sent as a single prompt.

Project context (--with-context)

By default a review sees only the diff. With --with-context (ADR-0017) the agentic host CLI is allowed to read other files in the repository — callers of the changed code, type and interface definitions, sibling modules, the project's own conventions and docs — to ground its review in how the change fits the wider codebase. The diff stays the subject of the review; the rest is background. The flag is CLI-providers-only: an API provider has no filesystem and the flag errors there, pointing you at --cli.

In context mode the host CLI runs read-only (it never modifies your tree) and with its working directory pinned to the repository root so its relative reads resolve there. The per-CLI flags (confirmed by a live smoke on 2026-05-29):

CLI	Diff-only (default)	--with-context adds
claude-cli	-p - --output-format text	--allowedTools Read,Grep,Glob (comma-separated; -p mode has no tools by default)
gemini-cli	-p <prompt>	--approval-mode plan --skip-trust (plan = read-only; skip-trust avoids the untrusted-dir downgrade)
codex-cli	exec --sandbox read-only --skip-git-repo-check <prompt>	(unchanged — the read-only sandbox already permits reads)

Write and network-mutation capabilities are never granted in either mode.

Caution

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 (Anthropic / OpenAI / Google), billed to your subscription. The pre-send secret scanner and the .commitbrief/** guard cover the diff only, not files the agent reads autonomously. A read-only sandbox blocks writes, not the model reading a file into its reasoning. CommitBrief prints a one-line caution on every --with-context run; the flag itself is your consent. Use it on repositories you trust. See [ADR-0017] in the project docs.

Caching: a --with-context run and a diff-only run on the same diff are stored under distinct cache keys, so they never replay each other. Note that context-mode results depend on files outside the diff, so an unchanged diff can yield a stale hit when neighbouring files change; TTL bounds this and --no-cache is the escape (see Cache).

Why stdin for claude-cli (UC-24)

Mid-to-large diffs combined with rules content frequently exceed the platform ARG_MAX limit (~128 KB on Linux/macOS) when the prompt is embedded in argv. Past that ceiling the subprocess exits with argument list too long instead of running. claude-cli switched to stdin transport in v0.9.2 (claude -p - reads the prompt from stdin) and the limit is gone.

gemini-cli stays on argv until upstream documents a reliable stdin shorthand. For huge diffs, prefer claude-cli or one of the API providers.

DefaultModel caching (UC-23, since v0.9.2)

DefaultModel() for CLI providers shells out to <binary> --version so cached entries can invalidate across host-CLI upgrades. The result is memoised per-Backend with sync.Once and the probe runs under a 5-second timeout — a hung host CLI cannot stall the review pipeline.

Pricing in the verbose footer

Both providers return provider.Pricing{} (all zero). The verbose footer shows token counts but — for the dollar amount, since you are paying through the host subscription, not per-token to us.

See also

• Providers — overview + capability comparison.
• Doctor command — provider connection pings.
• Output formats — plain-text vs structured rendering.