feat(widget): add cache-hit-rate widget#409
Open
sebryu wants to merge 1 commit into
Open
Conversation
Adds a Cache Hit Rate widget that mirrors the Anthropic Console's prompt-cache hit-rate formula: cache_read / (cache_read + cache_creation + fresh_input). Returns null on empty transcripts so it does not flash 0% before any tokens are recorded. Splits cacheReadTokens and cacheCreationTokens out of the existing cachedTokens roll-up on TokenMetrics (both new fields are optional and cachedTokens is preserved unchanged), so downstream widgets and configs are unaffected.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a
cache-hit-ratewidget that displays the prompt-cache hit rate for the current session, using the same formula the Anthropic Console reports.Formula:
Renders as
Cache: 87%(or87%in raw-value mode). Returnsnulluntil any cache or fresh-input tokens are seen, so it does not flash0%on empty transcripts.Why
Prompt-cache effectiveness is one of the most useful signals for tuning Claude Code workflows — high hit rate means cheaper, faster turns. It is visible on console.anthropic.com but there is no way to see it at a glance during a session. This widget surfaces the same number directly in the status line.
Changes
src/widgets/CacheHitRate.ts— new widget, follows the existing token-widget pattern (raw-value support, colors, preview)src/widgets/index.ts,src/utils/widget-manifest.ts— registercache-hit-ratesrc/types/TokenMetrics.ts— adds two optional fields:cacheReadTokensandcacheCreationTokens. The existingcachedTokens(read + creation) is preserved unchanged, so all existing widgets, configs, and downstream consumers are unaffectedsrc/utils/jsonl-metrics.ts— sumscache_read_input_tokensandcache_creation_input_tokensseparately while still rolling them intocachedTokenssrc/widgets/__tests__/CacheHitRate.test.ts— widget behaviour (null guards, formula, raw mode, preview)src/utils/__tests__/jsonl-metrics.test.ts— per-field aggregation in the existing fixturesNet diff: +177 / -3 across 7 files (3 of those are 1-line registrations/exports).
Compatibility
TokenMetrics.cachedTokenssemantics unchangedTokenMetricsare optionalTest plan
bun run lintpasses (tsc --noEmit+ ESLint--max-warnings=0)bun test— all 1401 tests pass, including 7 new widget tests and 6 added assertions in existing jsonl-metrics fixturesbun run src/ccstatusline.tsand verified the percentage matches what Anthropic Console reports for the same session