Cache command

Home / Commands / cache

commitbrief cache

Inspect and manage the local response cache. Four subcommands:

commitbrief cache clear
commitbrief cache prune [flags]
commitbrief cache stats
commitbrief cache inspect <key> [--show-content]

The parent command does nothing on its own.

Where the cache lives

<repo-root>/.commitbrief/cache/ — one JSON file per cached review. Cache key is a SHA-256 over diff + system_prompt + provider + model + lang + schema_version. Entries are written atomically (temp file + rename) so an interrupted write does not corrupt the store.

The cache is per-repo. commitbrief cache clear in one repo does not touch another repo's cache.

See Cache for the on-disk format and TTL behavior.

cache clear

Caution

Delete every cached entry for the current repo.

commitbrief cache clear

Reports the count and total byte size before the prompt so you can decide:

Found 142 cached entr(y/ies), 2.4 MB on disk at /repo/.commitbrief/cache.
Remove all cached entries?

  Yes  ▸ No        (←/→ to choose · Enter to confirm)

On a TTY the confirmation is an arrow-key Yes/No toggle (huh), pre-selected on No. Pass --yes to skip the prompt; in a non-TTY context without --yes the command aborts with Aborted; cache left untouched. (piped input falls back to the typed y/N line).

When the cache directory does not exist or is empty, the command prints No cached entries to remove (looked in <path>). and exits 0.

cache prune

Drop old and excess entries while keeping the rest. Defaults to --keep-last 500 --older-than 7d — entries survive when they sit inside both windows (newest 500 AND younger than 7 days).

commitbrief cache prune
commitbrief cache prune --keep-last=200 --older-than=14d
commitbrief cache prune --provider=anthropic --model=claude-opus-4-7

Flags

Flag	Default	Notes
--keep-last <N>	500	Keep the N newest entries (per the provider/model filter). 0 means keep nothing among the candidate pool. Negative values error.
--older-than <age>	7d	Delete entries older than this age. Units: d (day), w (week), m (month = 30d), y (year = 365d). h/m/s and bare integers error.
--provider <name>	(none)	Only consider entries matching this provider name.
--model <name>	(none)	Only consider entries matching this model identifier.

Calendar precision is deliberately approximate (m = 30d, y = 365d). Cache TTL does not need calendar arithmetic; "older than a month" gets what humans expect.

Output

Pruned 87 entr(y/ies) (1.2 MB); 213 remain.

The numbers refer to candidates within the provider/model filter (or all entries when those flags are unset). Entries outside the filter are untouched and not counted in the survivor total.

cache stats

Read-only summary of the cache: total entries and bytes, the oldest and newest entry timestamps, the configured size limit, and a per-provider/model breakdown.

commitbrief cache stats

Cache: 142 entr(y/ies), 2.4 MB at /repo/.commitbrief/cache.
Oldest 2026-05-20T08:14:02Z · newest 2026-05-28T19:41:55Z.
Size limit: unlimited (set cache.max_size_mb to bound).

By provider/model:
  anthropic    claude-opus-4-7               128  2.2 MB
  openai       gpt-4o                         14  220.0 KB

When cache.max_size_mb is set, the size-limit line reflects it (e.g. Size limit: 50.0 MB (cache.max_size_mb=50)). When the cache is empty, the command prints No cached entries (looked in <path>). and exits 0.

cache inspect

Dump one entry's metadata by its cache key — the SHA-256 shown by --verbose and dry-run. The .json suffix is optional.

commitbrief cache inspect <key>
commitbrief cache inspect <key> --show-content

Key:       3f9a…
Provider:  anthropic
Model:     claude-opus-4-7
Lang:      en
Created:   2026-05-26T01:23:45Z
TTL:       604800s (expires 2026-06-02T01:23:45Z, fresh)
Format:    json
Size:      3.4 KB
Tokens:    input=4231 output=1503 cached=0
Diff hash: sha256:abc…

The cached review body is omitted unless --show-content is passed. An unknown key prints No cache entry with key "<key>" (looked in <path>). and exits 0.

Size-bounded eviction

Set cache.max_size_mb (an integer > 0) in config to bound the on-disk cache. After each cache write, if the directory exceeds the limit the oldest entries (by created-at) are evicted oldest-first until it fits; the entry just written is never evicted, so a single entry larger than the cap survives over-budget. The default 0 means unlimited — cache prune stays the manual stand-in. See Configuration files.

Examples

# Default prune: keep 500 newest + everything from the last 7 days.
commitbrief cache prune

# Keep only the last 50 entries; everything else gone.
commitbrief cache prune --keep-last=50 --older-than=0d

# Drop only the long tail of an outdated model.
commitbrief cache prune --provider=anthropic --model=claude-3-opus

# Wipe everything for this repo (no recovery).
commitbrief cache clear --yes

See also

• Cache — entry format + TTL semantics + cache-hit reporting.
• Review command — --no-cache to bypass per-invocation.
• Dry-run command — shows the cache key for a review.
• Configuration files — where per-repo state lives.