Caching

llm-usage-metrics uses caching to keep runs fast, stable offline, and predictable.

Why caching exists

Cache	Purpose	Default TTL	Location
update-check cache	avoids querying npm on every startup	1 hour	`<platform-cache-root>/llm-usage-metrics/update-check.json`
pricing cache	stores normalized LiteLLM pricing data	24 hours	`<platform-cache-root>/llm-usage-metrics/litellm-pricing-cache.json`
event store	stores parsed file diagnostics/events and retained departed-file history	no TTL	`<platform-cache-root>/llm-usage-metrics/events.db`

On Linux with no XDG_CACHE_HOME, <platform-cache-root> defaults to ~/.cache.

read cached npm version if still fresh
otherwise perform a bounded fetch (default 1s timeout) for the latest version so the update hint stays consistent across commands
on fetch failure, fallback to previous cached version when available
optional session-scoped mode creates a per-shell cache file
skipped entirely for --help, --version, npx, and direct source/development runs

Relevant config keys/env vars:

tries fresh cache first
if cache is stale and network is enabled, fetches LiteLLM pricing and rewrites cache
if network fails, falls back to stale cache when possible
for the default LiteLLM URL, falls back to the bundled snapshot when cache and network are unavailable
with --pricing-offline, skips network and uses fresh cache, stale cache, or the bundled snapshot

Relevant options/config:

enabled by default
key is (source, file path)
validity requires matching dependency fingerprints
stores parse diagnostics and normalized events
dependency fingerprints include the primary file and any adapter-declared sidecar inputs
persisted as SQLite with per-file replace-on-change writes
--history includes usage from files that no longer exist on disk
moved, renamed, and copied files are suppressed by content hash to avoid double counting
llm-usage prune previews or deletes departed-file rows explicitly
first run after a store schema upgrade migrates the database in place and may take a few seconds
deleting the database file deletes retained local history and starts a new ledger on the next run
legacy JSON cache shards are ignored and safe to delete manually

Prune is dry-run by default:

llm-usage prune --suppressed

Selectors:

--suppressed selects departed files that --history already suppresses as moved or duplicated. Applying this selector does not change report output.
--departed-before YYYY-MM-DD selects departed files whose newest event timestamp is strictly older than that UTC date. Applying this selector permanently deletes retained history for those files.

Apply selected candidates:

llm-usage prune --suppressed --apply
llm-usage prune --departed-before 2026-01-01 --apply

After an applying run, the CLI deletes selected rows, runs SQLite VACUUM, and reports reclaimed database/WAL bytes.

Relevant env vars:

Avoid network pricing fetches:

llm-usage monthly --pricing-offline

Increase parsing throughput:

parseMaxParallel = 16
parseWorkers = 4

Shorten pricing cache TTL to 2 hours:

[pricing]
cacheTtlMs = 7200000

When pricing uses the bundled snapshot, stderr shows its snapshot date; run once without --pricing-offline to refresh the cache.
Custom --pricing-url values use their matching cache or network source and do not fall back to the bundled default snapshot.
For stale reports after source file changes, verify source files updated mtime. Deleting <platform-cache-root>/llm-usage-metrics/events.db starts a fresh ledger, but it also deletes retained history used by --history.
To force update checks every run, set update.cacheTtlMs = 0 in the config file.