nntrivi2001
17d56d0e01
Clean break, no compatibility alias. Renames the product name, the CLI binary (`ccam` -> `agenthub`), the env var prefix (`CCAM_` -> `AGENTHUB_`), the Prometheus metric namespace (`ccam_*` -> `agenthub_*`), the tmux session prefix (`ccam-lane-<id>` -> `agenthub-lane-<id>`), the per-repo runtime profile directory (`.ccam/profile` -> `.agenthub/profile`), the lanes state root (`~/.claude/ccam-lanes` -> `~/.claude/agenthub-lanes`), the bundled plugins (`plugins/ccam*` -> `plugins/agenthub*`) and their slash commands (`/ccam-doctor` -> `/agenthub-doctor`, `/ccam:*` -> `/agenthub:*`). Because there is no alias, an existing install has to be updated by hand: rename its `.ccam/profile` directory and any `CCAM_*` variables, and reinstall the plugin under its new name. Two other name families are deliberately left alone here, since they are not just strings: the `Claude-Code-Monitor` repository/marketplace name, and the `agent-dashboard` npm package plus its `~/.claude/agent-dashboard` runtime directory, which holds the live database and needs a migration rather than a rename. Verified: server 1406/1406, client 459/459, `grep -i ccam` clean across tracked files, `openapi.yaml` regenerated (95 paths, unchanged count).
3.8 KiB
description
| description |
|---|
| Analyze prompt-cache effectiveness for Claude Code usage from the Agent Monitor dashboard — cache hit rate (total_cache_read / (total_cache_read + total_input)), cache_write vs cache_read reuse, cache-read vs cache-write spend, and the sessions with the poorest reuse. Pulls token totals from /api/analytics, per-session detail from /api/sessions, and dollar splits from /api/pricing/cost. Use when diagnosing cache spend or deciding whether prompt caching is paying off. |
Cache Efficiency
Diagnose whether prompt caching is actually saving money, and where it is not.
Input
The user provides: $ARGUMENTS
This may be: empty (analyze the whole fleet), "today" / "this week" / a date range, a session ID to scope the analysis, or a target like "hit rate > 80%". When empty, analyze all data from /api/analytics.
Data Sources
| Endpoint | Returns |
|---|---|
GET /api/analytics |
tokens.total_input, tokens.total_output, tokens.total_cache_read, tokens.total_cache_write (baselines pre-summed), plus daily_sessions |
GET /api/sessions?limit=200 |
Session list — each has model, cwd, started_at, ended_at, inline cost, metadata (JSON: usage_extras with cache token detail) |
GET /api/sessions/{id} |
Full session detail with nested agents and events, for drill-down on a flagged session |
GET /api/pricing/cost |
{ total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] } — used to price cache read vs write spend |
How cache economics work
cache_hit_rate = total_cache_read / (total_cache_read + total_input)
cache_reuse = total_cache_read / total_cache_write
cache_read_cost = (cache_read_tokens / 1M) × cache_read_per_mtok
cache_write_cost = (cache_write_tokens / 1M) × cache_write_per_mtok
Cache writes cost more per token than cache reads (e.g. Sonnet $3.75 write vs $0.30 read per Mtok), and writes are billed even if the cached block is never reused. The payoff only arrives on subsequent reads — so a healthy fleet shows cache_read_tokens far exceeding cache_write_tokens. When cache_reuse < 1, you are paying to cache context you barely re-read.
Token counts are effective totals = current + baseline (baselines preserve pre-compaction tokens).
Report Sections
1. Fleet Cache Hit Rate
From /api/analytics: compute cache_hit_rate × 100. State raw total_cache_read and total_input. Benchmark: >70% strong, 40–70% moderate, <40% weak prompt-cache utilization.
2. Write vs Read Reuse
Compute cache_reuse = total_cache_read / total_cache_write. Show both token counts. Flag if reuse < 1 (writing more cache than is ever read back).
3. Cache Spend Split
From /api/pricing/cost breakdown, sum cache_read_cost and cache_write_cost across all models. Show the dollar split and what fraction of total cost is cache-write overhead vs cache-read savings.
4. Sessions With Poor Reuse
From /api/sessions?limit=200, parse metadata.usage_extras for per-session cache read/write where available; rank sessions by lowest read/write reuse (and by cache_write-heavy cost). List the worst 10 with model, cost, and reuse ratio. Use /api/sessions/{id} to drill into any single flagged session.
5. Recommendations
- Sessions where
cache_write >> cache_read: short or one-shot sessions rarely recoup cache writes — note them. - Stable, repeated context (system prompts, large files) should be cached once and reused; high churn defeats caching.
- Estimate the dollar impact of raising the hit rate to the next benchmark tier.
Output
Structured Markdown with tables. Currency as USD to 4 decimal places; rates as $/Mtok; percentages with ▲/▼ for any trend. Token counts with thousands separators.