feat(cli): show prompt cache hit rate in status bar

Add a ◎ XX% indicator to the CLI status bar showing the prompt cache
hit rate (cache_read / prompt_tokens). This helps users monitor how
effectively their provider's prompt caching is working.

Features:
- Color-coded: green (≥70%), yellow (40-70%), red (<40%)
- Adaptive precision: integer on narrow terminals, one decimal on wide
- Only shown when cache data is available (provider supports it)
- Compatible with OpenAI, Anthropic, DeepSeek, xiaomi, and other
  providers that return prompt_tokens_details.cached_tokens

Tests: 6 new test cases, 43/43 passing
This commit is contained in:
Cheri Wen
2026-06-05 19:03:02 +08:00
committed by Teknium
parent fb786d2f5b
commit 4bc7e624d6
3 changed files with 138 additions and 0 deletions
+33
View File
@@ -6178,6 +6178,27 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
return "class:status-bar-warn"
return "class:status-bar-good"
def _cache_hit_rate(self, snapshot: dict, precision: int = 1) -> "tuple[float, str] | None":
"""Return (cache_pct, formatted_label) or None if no cache data.
Centralises the cache-hit-rate computation so both the plain-text
status bar and the prompt-toolkit fragment path share one formula.
"""
cache_read = snapshot.get("session_cache_read_tokens", 0)
prompt_total = snapshot.get("session_prompt_tokens", 0)
if cache_read > 0 and prompt_total > 0:
cache_pct = cache_read / prompt_total * 100
return cache_pct, f"◎ {cache_pct:.{precision}f}%"
return None
def _cache_hit_rate_style(self, cache_pct: float) -> str:
"""Style for cache hit rate — higher is better (opposite of context %)."""
if cache_pct >= 70:
return "class:status-bar-good"
if cache_pct >= 40:
return "class:status-bar-warn"
return "class:status-bar-bad"
@staticmethod
def _battery_status_style(category: str) -> str:
"""Map a battery colour category to a status-bar style class."""
@@ -7244,6 +7265,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
parts.append(f"⚕ {snapshot['model_short']}")
if _ok("context_pct"):
parts.append(percent_label)
cache = self._cache_hit_rate(snapshot, precision=0)
if cache and _ok("cache_hit"):
parts.append(cache[1])
if battery_label:
parts.insert(0, battery_label)
compressions = snapshot.get("compressions", 0)
@@ -7286,6 +7310,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
if battery_label:
parts.insert(0, battery_label)
compressions = snapshot.get("compressions", 0)
cache = self._cache_hit_rate(snapshot)
if cache and _ok("cache_hit"):
parts.append(cache[1])
if compressions and _ok("compressions"):
parts.append(f"🗜️ {compressions}")
bg_count = snapshot.get("active_background_tasks", 0)
@@ -7388,6 +7415,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
frags.append(("class:status-bar-strong", snapshot["model_short"]))
if _ok("context_pct"):
_append(frags, " · ", (self._status_bar_context_style(percent), percent_label))
cache = self._cache_hit_rate(snapshot, precision=0)
if cache and _ok("cache_hit"):
_append(frags, " · ", (self._cache_hit_rate_style(cache[0]), cache[1]))
if compressions and _ok("compressions"):
_append(frags, " · ", (self._compression_count_style(compressions), f"🗜️ {compressions}"))
if bg_count and _ok("bg_tasks"):
@@ -7436,6 +7466,9 @@ class HermesCLI(CLIAgentSetupMixin, CLICommandsMixin, CLIBillingMixin):
("class:status-bar-dim", " "),
(bar_style, percent_label),
)
cache = self._cache_hit_rate(snapshot)
if cache and _ok("cache_hit"):
_append(frags, " │ ", (self._cache_hit_rate_style(cache[0]), cache[1]))
if compressions and _ok("compressions"):
_append(frags, " │ ", (self._compression_count_style(compressions), f"🗜️ {compressions}"))
if bg_count and _ok("bg_tasks"):
+1
View File
@@ -0,0 +1 @@
CheriWen
+104
View File
@@ -508,3 +508,107 @@ class TestStatusBarFieldConfig:
with patch.object(cli_mod, "CLI_CONFIG", {"display": {"status_bar": {"fields": ["duration"]}}}):
second = cli_obj._get_status_bar_field_set()
assert first == second == frozenset({"model"})
class TestCacheHitRate:
def test_cache_hit_rate_shown_in_wide_terminal(self):
cli_obj = _attach_agent(
_make_cli(),
prompt_tokens=10_000,
completion_tokens=2_000,
total_tokens=12_000,
api_calls=5,
context_tokens=12_000,
context_length=200_000,
cache_read_tokens=7600,
cache_write_tokens=0,
)
text = cli_obj._build_status_bar_text(width=120)
assert "◎ 76.0%" in text
def test_cache_hit_rate_shown_in_narrow_terminal(self):
cli_obj = _attach_agent(
_make_cli(),
prompt_tokens=10_000,
completion_tokens=2_000,
total_tokens=12_000,
api_calls=5,
context_tokens=12_000,
context_length=200_000,
cache_read_tokens=5000,
cache_write_tokens=0,
)
text = cli_obj._build_status_bar_text(width=60)
assert "◎ 50%" in text
def test_cache_hit_rate_hidden_when_zero(self):
cli_obj = _attach_agent(
_make_cli(),
prompt_tokens=10_000,
completion_tokens=2_000,
total_tokens=12_000,
api_calls=5,
context_tokens=12_000,
context_length=200_000,
cache_read_tokens=0,
cache_write_tokens=0,
)
text = cli_obj._build_status_bar_text(width=120)
assert "◎" not in text
def test_cache_hit_rate_hidden_when_no_data(self):
cli_obj = _attach_agent(
_make_cli(),
prompt_tokens=10_000,
completion_tokens=2_000,
total_tokens=12_000,
api_calls=5,
context_tokens=12_000,
context_length=200_000,
)
text = cli_obj._build_status_bar_text(width=120)
assert "◎" not in text
def test_cache_hit_rate_one_decimal(self):
cli_obj = _attach_agent(
_make_cli(),
prompt_tokens=10_000,
completion_tokens=2_000,
total_tokens=12_000,
api_calls=5,
context_tokens=12_000,
context_length=200_000,
cache_read_tokens=7620,
cache_write_tokens=0,
)
text = cli_obj._build_status_bar_text(width=120)
assert "◎ 76.2%" in text
def test_cache_hit_rate_with_anthropic_style_cache(self):
"""Anthropic has both cache_read and cache_write"""
cli_obj = _attach_agent(
_make_cli(),
prompt_tokens=10_000,
completion_tokens=2_000,
total_tokens=12_000,
api_calls=5,
context_tokens=12_000,
context_length=200_000,
cache_read_tokens=5000,
cache_write_tokens=2000,
)
text = cli_obj._build_status_bar_text(width=120)
# cache_read / prompt_tokens = 5000 / 10000 = 50%
assert "◎ 50.0%" in text