Caching model

planwerk-agent caches the result of every expensive Claude analysis on disk so that re-running a command against an unchanged input is free. The cache is shared by review, propose, audit, elaborate, and gap-analysis, and is keyed by repository plus a content fingerprint plus the flags that affect the result.

What the cache key is built from

Each command derives its key from the state that would change the analysis, so the cache invalidates automatically when that state changes:

• Review — the PR HEAD SHA. This avoids repeated reviews of an unchanged PR state.
• Propose — the default-branch HEAD SHA, resolved via gh api graphql (so private repos work). Proposals refresh when the repo changes.
• Audit — the default-branch HEAD SHA together with the set of flags that affect the audit.
• Gap analysis — the default-branch HEAD SHA, folded together with --feature and --file so a single-feature run never overwrites the full-repo result. The SHA is fetched first so a cache hit can short-circuit the clone entirely.
• Elaborate — repository plus HEAD plus issue number plus a fingerprint of the issue body, so the cache invalidates when either the repo or the issue is edited. With the wiki enabled, the resolved wiki commit is part of the key too, because the wiki's review patterns and the project memory reach the prompt. A run without a wiki has no wiki part in its key. A run whose wiki loaded while its commit could not be resolved has no key that covers the wiki, so it neither reads nor writes the cache.

A review, audit, propose, or elaborate run whose session may search the local mirror (--brain) carries the mirror's revision in its key, the items cursor and the wiki commit, because the result came from a session that could search the mirror in that state. A run without the search has no such part in its key.

Entries are written under the user cache directory. Both propose and audit fetch the default-branch HEAD SHA via git ls-remote before cloning, so a hit avoids the clone.

The same directory holds one thing that is not a cache entry: the mirror that brain sync keeps of a repository's issues, pull requests, commit list, and wiki, under brain/<owner>/<name>. It has no key and no age. --clear-cache removes cache entries only and leaves the mirror; brain sync --full rebuilds it, and deleting the directory removes it. The search index of brain search is a file in that directory.

What every key is scoped to

On top of the per-command state above, every key carries the configuration that shapes the analysis itself:

• The Claude tiers — the resolved --claude-model, --claude-effort, --structure-model, --structure-effort, --finder-model and --finder-effort. A review by Sonnet and a review by Fable are different analyses of the same diff, so they are different entries. Re-running with a stronger model gives you that model's findings, not a hit on the weaker run.
• The pattern sources — the --patterns sources in order, whether --no-repo-patterns / --no-local-patterns suppressed a catalog, and --max-patterns. The loaded catalog decides what the analysis looks for, so adding a rule directory invalidates the entry rather than serving a result from a run that never saw those rules.

What only shapes the rendering is deliberately absent. --min-severity and --min-confidence filter a stored payload on the way out, so asking the same commit for a stricter view reuses the analysis instead of repeating it. The flags that change what is analyzed — --thorough, --specialists, --coverage-map — do belong in the key, and a review entry stores the coverage map beside its findings so a --coverage-map run that hits the cache still renders the section it asked for.

The tool version is deliberately not part of the key: a new release would otherwise discard every entry, and --no-cache is the switch for re-running against changed prompts.

Controlling the cache

• --no-cache forces a fresh run, ignoring any cached entry.
• --clear-cache (with optional --clear-cache-scope) wipes cached entries.
• --cache-max-age rejects entries older than a given duration (where supported).

See the CLI reference for the exact flags on each command.

Inspecting the cache

The cache subcommand gives visibility into what is stored:

• cache stats shows total entries, on-disk size, the age distribution, and a per-command breakdown — useful before running --clear-cache to decide whether you actually need a full wipe.
• cache inspect <key> dumps the cached command, writtenAt, age, size, and the full JSON payload for a single entry, so you can confirm what would be reused on the next run without rerunning the analysis.