Skip to main content
subagent CX Codex

token-economist — Claude Code subagent: what it does, how to install

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

MIT ★ 1,198 updated 2026-10-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-analytics@claude-code-agent-monitor-plugins
Open on GitHub

What token-economist 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.

What it helps with

  • 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 for the agent

  • 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

How to install token-economist

1Plugin marketplace

/plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor
/plugin install ccam-analytics@claude-code-agent-monitor-plugins

2Manually: put the files in place

.claude/agents/token-economist.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about token-economist

How to install token-economist in Claude Code?

Run /plugin marketplace add hoangsonww/Claude-Code-Agent-Monitor followed by /plugin install ccam-analytics@claude-code-agent-monitor-plugins.

What does token-economist do?

It pulls usage metrics from the local Agent Monitor API, checks cache efficiency, analyzes model costs, and provides up to five dollar-quantified tactics to trim token spend.

What are the requirements to run token-economist?

The Agent Monitor web service must be actively running at http://localhost:4820, which requires running npm start from its repository root.

Source text

token-economist.md · MIT
---
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.
5. **Model mix**: For each model family, compute its share of total tokens vs. share of total cost; surface premium models doing low-complexity work (cross-check session metadata and subagent types).
6. **Token-reduction tactics**: Translate each finding into a concrete action with an estimated dollar/percentage impact.

## Output Standards

- Cite specific numbers from the API — never use vague qualifiers.
- Format currency as USD to 4 decimal places.
- Express token counts with thousands separators; show rates as $/Mtok.
- Show percentage and trend changes with ▲/▼ indicators.
- Rank token-reduction tactics by estimated savings (descending); cap at top 5.
- Attach a confidence level (high/medium/low) to each recommendation.

## Constraints

- Read-only advisory role — never modify any data.
- Only use data returned by the API — never fabricate metrics.
- If the dashboard is unreachable, tell the user to start it with `npm start` from the repo root.

© Son Nguyen · MIT · hoangsonww/Claude-Code-Agent-Monitor

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set155

The whole set →
file-headers file-headers — a skill that makes coding agents add a header with author and overview to every source file they create or edit. Useful for repos that need one consistent copyright format. CX Codex +1 ★ 1,198repo stars orchestration-analyst Multi-agent orchestration analyst. Builds DAG topology maps, pinpoints serialization bottlenecks, and tracks error propagation through local Agent Monitor datasets. CX Codex ★ 1,198repo stars session-investigator session-investigator examines one Claude Code session through Agent Monitor data, covering cost, agents, events, transcript signals, and anomalies. Use it to trace failures. CX Codex ★ 1,198repo stars db-inspector db-inspector — a read-only subagent that cross-checks the Agent Monitor dashboard API for orphaned events, sessions with no subagent records and sessions stuck in active. CX Codex ★ 1,198repo stars config-auditor config-auditor reviews Claude Code settings and file-based memory through the Agent Monitor API. Use it to spot duplicates, risky hooks, scope sprawl, and stale facts. CX Codex ★ 1,198repo stars budget-sentinel budget-sentinel compares your Claude spend with a target budget, projects where the period will end and points at the sessions pushing costs up. CX Codex ★ 1,198repo stars wiki-i18n wiki-i18n enforces localization into Chinese, Vietnamese, Korean, and Spanish whenever static wiki pages or scripts are edited. CX Codex +1 ★ 1,198repo stars push-to-forked-pr The push-to-forked-pr skill sends your current changes to a pull request branch hosted on a fork. Use it when you need to update the PR without creating a branch. CX Codex +1 ★ 1,198repo stars

Project sponsors

Companies that keep this analytics open