Configuration files

Home / Configuration / Configuration files

Configuration files

CommitBrief uses a two-tier YAML configuration with field-level merge.

Files

Tier	Path	Notes
User-level	~/.commitbrief/config.yml	Defaults that apply everywhere.
Repo-local	<repo-root>/.commitbrief/config.yml	Per-repo overrides. Gitignored — auto-added on first write.

Either file may be absent; commitbrief.Default() fills in a reasonable skeleton when both are missing.

The user-level path can be overridden via the COMMITBRIEF_CONFIG environment variable — see Environment variables.

Merge order (lowest → highest priority)

1. config.Default() skeleton (built into the binary).
2. User-level YAML (~/.commitbrief/config.yml).
3. Repo-local YAML (<repo>/.commitbrief/config.yml).
4. Environment variables (see Environment variables).
5. CLI flag overrides (--provider, --model, --lang).

Higher entries override lower ones on a field-by-field basis, not whole-file replacement. So a repo-local providers.openai.model: gpt-4o-mini overrides only that field, not the user-level Anthropic key.

YAML schema

version: 1                                   # schema version (currently 1)
provider: anthropic                          # active provider name
providers:                                   # per-provider settings
  anthropic:
    api_key: sk-ant-...                      # secret; never logged
    model: claude-opus-4-8
  openai:
    api_key: sk-...
    model: gpt-4o
    pricing:                                 # optional: override built-in $/1M rates (OQ-09)
      gpt-4o:
        input_per_1m: 2.50
        output_per_1m: 10.00                 # omitted/zero fields keep the built-in value
        cached_input_per_1m: 1.25
  deepseek: { api_key: sk-... }              # + mistral, cohere — see [Providers](Providers)
  gemini:
    api_key: AIza...
    model: gemini-2.5-pro
  ollama:
    base_url: http://localhost:11434         # no api_key for Ollama
    model: qwen2.5-coder:14b
  claude-cli:                                # uses local `claude` binary
    model: ""                                # ignored; CLI manages its own
  gemini-cli:                                # uses local `gemini` binary
    model: ""
output:
  lang: en                                   # supported: en | tr; unsupported codes coerce to en
  stream: true                               # currently unused but reserved
  color: auto                                # auto | always | never (overridden by --color)
cache:
  enabled: true                              # false skips cache lookups + writes entirely
  ttl_days: 7                                # entry expiry; 0 falls back to DefaultTTL = 7 days
  max_size_mb: 0                             # on-disk cap; 0 = unlimited; >0 evicts oldest entries past the cap
guard:
  secret_scan: true                          # false disables the credential scanner
  token_preflight: false                      # opt-in: confirm/abort when the prompt overflows the model's context window
  injection_scan: true                        # warn (never abort) if a non-default COMMITBRIEF.md/OUTPUT.md has injection phrasing
  secret_patterns:                            # additive user credential regexes; built-ins always run (ADR-0024)
    - name: "Internal Service Token"
      regex: 'INT-[0-9]{10}'
cost:
  warn_threshold_usd: 0.50                   # prompt-or-abort if estimated cost > threshold; <=0 disables
command:
  default: ""                                # args for a bare `commitbrief`; empty = --staged (e.g. "--unstaged --cli gemini")
commit:
  type: plain                                # default --type for `commitbrief commit`
  generate: 1                                # default --generate (alternatives to offer)
review:
  flaky: true                                # deterministic flaky-test detector pre-pass (ADR-0022); --no-flaky overrides per-run
  sandbox_rerun: 0                            # opt-in sandbox-rerun confirmation (ADR-0022): re-run a flagged test N times in isolation; 0 = off; --sandbox-rerun[=N] overrides per-run
  sandbox_command: []                         # the rerun executor (ADR-0033): argv list (NOT a shell string), e.g. ["go", "test", "-run", "^{{.Test}}$", "./..."]; requires sandbox_rerun > 0 too (double opt-in, either alone is a no-op); hand-edit only, `config set` rejects this key; never runs on `mcp`/`guard`; test-name resolution is Go-only
  architecture: true                         # architecture-aware review (ADR-0030): read architecture.json into the prompt; --no-architecture overrides per-run
  architecture_file: ""                      # override the architecture.json discovery path (relative to repo root, or absolute); empty = auto-discover

Note

cache.max_size_mb returned as a real key in v1.3.0 (size-bounded eviction). It was removed in v0.9.1 as dead config; the v1.3.0 key is read on the Put path. 0 (the default) keeps the cache unlimited.

Per-field reference

Dotted path	Type	Default	Notes
version	int	1	Schema version. Currently always 1; bumped on a breaking schema change.
provider	string	anthropic	Active provider. Must match a registered provider name.
providers.<name>.api_key	string	(empty)	Provider API key. Not used by ollama, claude-cli, gemini-cli.
providers.<name>.model	string	(empty)	Provider-specific model. Empty → use provider's DefaultModel().
providers.<name>.base_url	string	(empty for most; http://localhost:11434 for ollama via defaults)	Override the API endpoint. Used by ollama and the OpenAI-compatible providers.
providers.<name>.pricing.<model>.input_per_1m	float	(built-in)	Override the input rate ($/1M tokens) for one model (OQ-09). Zero/omitted → built-in snapshot. Affects cost preflight, verbose footer, cached cost.
providers.<name>.pricing.<model>.output_per_1m	float	(built-in)	Override the output rate ($/1M tokens).
providers.<name>.pricing.<model>.cached_input_per_1m	float	(built-in)	Override the cached-input rate ($/1M tokens).
output.lang	string	en	AI output language (any recognized language, e.g. en/tr/fr/de). The CLI interface localizes only for en/tr, else English. Chain --lang→repo→user→English; invalid/empty falls through. config set validates (ADR-0021).
output.stream	bool	true	Currently reserved; not used at runtime.
output.color	string	auto	auto / always / never. The --color flag overrides this.
cache.enabled	bool	true	false skips both cache reads and writes for the entire run.
cache.ttl_days	int	7	Entry expiry in days. Cannot be negative. 0 → cache.DefaultTTL (7 days).
cache.max_size_mb	int	0	On-disk cache cap in MiB. Cannot be negative. 0 = unlimited. When >0, each write that pushes the cache past the cap evicts the oldest entries first (the just-written entry is never evicted). Inspect with cache stats / cache inspect.
guard.secret_scan	bool	true	false disables the pre-send credential scanner entirely (master switch for both built-in and user patterns).
guard.token_preflight	bool	false	Opt-in. When true, a review whose estimated prompt (chars/4 heuristic) exceeds the provider's context window prompts for confirmation on a TTY, or aborts non-interactively, before the paid call — instead of a raw provider 400. Off by default so a heuristic false positive never blocks an unguarded review (ADR-0003).
guard.secret_patterns	list of {name, regex}	[]	Additive user credential regexes layered on top of the built-in eight (ADR-0024). Built-ins always run and cannot be disabled here — use secret_scan: false for that. On a name collision the built-in wins. Each regex is a Go regexp (RE2) expression; an invalid one aborts the review before any provider call, naming the offending pattern. As with the built-ins, only line numbers + pattern names are ever reported, never the matched text. commitbrief config get guard.secret_patterns lists the configured names; config set is rejected (edit the YAML directly, like providers.*.pricing.*).
guard.injection_scan	bool	true	When true, a non-default COMMITBRIEF.md / OUTPUT.md is scanned for prompt-injection phrasing ("ignore previous instructions", "you are now", "system prompt", etc., case-insensitive). On a hit the CLI prints a warning to stderr (file + line numbers) and continues — it never aborts, because it's your own file (ADR-0025). Defense-in-depth visibility next to the passive <project_rules> immutability wrap. The embedded default rules are trusted and skipped. Set false to silence the warning.
cost.warn_threshold_usd	float	0.50	Cost ceiling above which the preflight prompts (TTY) or aborts (non-TTY). 0 or negative disables.
command.default	string	""	Argument string applied to a bare commitbrief (no args) — e.g. --unstaged --cli gemini. Bypassed the moment any flag/subcommand is passed. Empty = built-in --staged. Whitespace-split; no shell quoting.
commit.type	string	plain	Default --type for commitbrief commit. One of plain, conventional, conventional+body, gitmoji, subject+body. Overridden by the --type flag.
commit.generate	int	1	Default --generate for commitbrief commit — how many message alternatives to offer (1–10). Overridden by the --generate flag.
review.flaky	bool	true	Run the deterministic flaky-test detector pre-pass (ADR-0022) for API/mock providers. false disables it; the --no-flaky flag overrides per-run. See Review.
review.sandbox_rerun	int	0	Opt-in sandbox-rerun confirmation (ADR-0022/ADR-0033): re-run a flagged test N times in isolation. 0 = off. Only takes effect together with a non-empty review.sandbox_command below (double opt-in) — this key alone is a no-op. --sandbox-rerun[=N] overrides per-run. See Review.
review.sandbox_command	list of strings	[]	The sandbox-rerun executor (ADR-0033): a list of argv elements, not a shell string, each a Go text/template over {{.File}}/{{.Line}}/{{.Test}}, run with no shell via exec.CommandContext. Requires review.sandbox_rerun > 0 too. Hand-edit only — config set review.sandbox_command is rejected, same treatment as guard.secret_patterns. Runs against the working tree, not the staged snapshot. Never runs on commitbrief mcp or commitbrief guard. Test-name resolution is Go-only — non-Go files skip the rerun (stderr warning) and keep their bare static finding. See Review.
review.architecture	bool	true	Architecture-aware review (ADR-0030): when an architecture.json (archlint's config) is present, inject a summary of its layers + import-boundary rules into the prompt so the LLM can flag boundary-crossing imports. One-way read; missing/malformed file = no-op. false disables it; --no-architecture overrides per-run. See Architecture-aware review.
review.architecture_file	string	""	Override the architecture.json discovery path (relative to the repo root, or absolute). Empty = auto-discover architecture.json at the repo root. A configured-but-missing path is an error.

Editing the files

Three options:

1. Interactive: commitbrief setup (rewrites the provider/model block for one provider; non-destructive for others).
2. Programmatic: commitbrief config set <key> <value> — see Config command.
3. Hand-edit the YAML files directly. Hand-edits are loaded atomically on the next CLI invocation; no daemon to restart.

File modes and permissions

• ~/.commitbrief/config.yml is written 0600 (owner read/write). The directory is 0700.
• <repo>/.commitbrief/config.yml is written 0600. The .commitbrief/ directory is 0700. The repo's .gitignore is updated to include .commitbrief/ if not already present.

API keys are masked when printed by commitbrief config show and commitbrief providers list; they never appear in logs.

See also

• Environment variables — env overrides and precedence.
• Global flags — flags that override config.
• Config command — read and set config keys.
• Providers — per-provider settings reference.