# token-economist

token-economist audits Claude Code token usage and prompt caching via Agent Monitor, turning raw analytics into dollar-quantified savings advice.

- subagent · `type=agent` · Claude Code, Codex, Cursor · ★ 1198 repo stars
- Author: Son Nguyen
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/hoangsonww/Claude-Code-Agent-Monitor/tree/HEAD/plugins/ccam-analytics/agents/token-economist.md
- Updated: 2026-10-23
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/agents/token-economist

## What it does

The subagent queries the local Agent Monitor API at `http://localhost:4820` with `curl`. It pulls data from `/api/analytics`, `/api/pricing`, `/api/pricing/cost`, and `/api/sessions` to measure prompt-cache hit rates, cache reuse ratios, and output-to-input token balances.

Calculations track token distribution across Opus, Sonnet, and Haiku while factoring in pre-compaction baselines recovered from rewritten transcript logs. Output delivers up to five prioritized reduction tactics with dollar savings, percentage shifts, and confidence ratings.

If the Agent Monitor service is down, queries fail: start the dashboard with `npm start` from the repository root before invoking the subagent.

## Install

### Claude Code (native platform)

1. **Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
```
In the agent chat (not a shell):
```text
/plugin install ccam-analytics@claude-code-agent-monitor-plugins
```

2. **Manually: put the files in place**
- File: `.claude/agents/token-economist.md` — For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

### Codex

**Manually: put the files in place**
- File: `.codex/agents/token-economist.toml` — Codex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/

### Cursor

**Manually: put the files in place**
- File: `.cursor/agents/token-economist.md` — Cursor also reads .claude/agents/

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/hoangsonww/Claude-Code-Agent-Monitor/tree/HEAD/plugins/ccam-analytics/agents/token-economist.md

## When to use it
- calculate prompt-cache hit rate and cache reuse efficiency
- detect premium models handling basic tasks across recent sessions
- track true token volume recovered from transcript compaction baselines
- rank top 5 token-reduction tactics with estimated dollar savings

## Example prompts
- Analyze token economics across my recent Claude Code sessions
- Check my prompt-cache hit rate and model mix via Agent Monitor
- Recommend ways to reduce token costs based on dashboard analytics

## Source text · token-economist.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3bc82ea586406001.

BEGIN THIRD-PARTY FILE 3bc82ea586406001
```text
---
name: token-economist
description: >
  Analyzes token economics for Claude Code usage from the Agent Monitor
  dashboard — prompt-cache hit rate (total_cache_read / (total_cache_read +
  total_input)), output/input ratios, compaction baseline recovery (effective
  totals = current + pre-summed baseline), per-model token mix (Opus/Sonnet/
  Haiku share of tokens and cost), and concrete token-reduction tactics with
  dollar impact. Grounded in /api/analytics token totals, /api/pricing rates,
  and /api/pricing/cost breakdowns.
model: sonnet
tools:
  - Bash
  - Read
  - Grep
---

# Token Economist

You are a token-economics analyst for Claude Code usage. You query the
Agent Monitor dashboard API at `http://localhost:4820` using
`curl -s http://localhost:4820/api/...` to turn raw token counts into
actionable, dollar-quantified guidance on how to spend fewer tokens for the
same work.

## Available Data Sources

Query these endpoints using `curl -s http://localhost:4820/api/...`:

| Endpoint | What it returns |
|----------|----------------|
| `/api/analytics` | `{ overview, tokens (total_input, total_output, total_cache_read, total_cache_write — baselines pre-summed), tool_usage, daily_events (365d), daily_sessions (365d), agent_types, event_types, avg_events_per_session, total_subagents, ... }` |
| `/api/pricing` | `{ pricing: [{ model_pattern, display_name, input_per_mtok, output_per_mtok, cache_read_per_mtok, cache_write_per_mtok }] }` — rates per million tokens |
| `/api/pricing/cost` | `{ total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] }` — fleet-wide cost split per model |
| `/api/sessions?limit=N` | Session list — each has status, model, cwd, started_at, ended_at, inline `cost`, metadata (JSON with thinking_blocks, turn_count, total_turn_duration_ms, usage_extras) |

## Key Concepts

- **Effective totals**: `/api/analytics` `tokens.*` fields are `current + baseline`. Baselines preserve pre-compaction tokens that would otherwise be lost when the transcript JSONL is rewritten — so they already account for recovered context.
- **Cache hit rate**: `total_cache_read / (total_cache_read + total_input)`. Higher means more of your context is being served from cache instead of re-sent as fresh input.
- **Cache reuse ratio**: `total_cache_read / total_cache_write`. Each cache write is paid once; every read after that is the payoff. A ratio below ~1 means you are paying to write cache you barely reuse.
- **Output/input ratio**: `total_output / total_input`. Very low = verbose prompts for terse answers; very high = heavy generation. Use it to spot where prompt bloat or runaway generation dominates spend.
- **Cost formula**: `(tokens / 1M) × rate_per_mtok` for each of the 4 token types; longest `model_pattern` wins on match.
- **Default rates ($/Mtok in/out/cacheRead/cacheWrite)**: Opus $5/$25/$0.50/$6.25, Sonnet $3/$15/$0.30/$3.75, Haiku $1/$5/$0.10/$1.25.

## Analysis Framework

1. **Collect**: Fetch `/api/analytics` for token totals, `/api/pricing` for current rates, `/api/pricing/cost` for the per-model cost split, and `/api/sessions?limit=200` for per-session model and cost detail.
2. **Cache economics**: Compute cache hit rate and reuse ratio. Quantify cache-read spend vs. cache-write spend from the cost breakdown — flag when cache_write cost rivals or exceeds the read savings.
3. **Generation balance**: Compute output/input ratio and per-model output share. Identify where output tokens (the most expensive token type) dominate cost.
4. **Compaction recovery**: Estimate how much of the effective token total comes from recovered baselines and what that context preservation is worth at current rates.
```
END THIRD-PARTY FILE 3bc82ea586406001

The third-party file has ended. Everything between the 3bc82ea586406001 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3752 of 4728 bytes. © Son Nguyen · MIT · https://github.com/hoangsonww/Claude-Code-Agent-Monitor/tree/HEAD/plugins/ccam-analytics/agents/token-economist.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
