Token usage tracking

Talon records token usage for every agent run. Input tokens, output tokens, cache reads, cache writes, and cost in USD are all stored in the runs table.

What’s tracked

Each record in the runs table includes:

Column	Description
`input_tokens`	Tokens sent to the model
`output_tokens`	Tokens generated by the model
`cache_read_tokens`	Tokens served from the provider’s prompt cache
`cache_write_tokens`	Tokens written to the provider’s prompt cache
`cost_usd`	Total cost for the run in USD, from the Agent SDK

These come directly from the Agent SDK result. No estimation — the provider’s reported values.

Viewing usage

talonctl status shows aggregate token usage:

npx talonctl status

For detailed per-run data, query the database directly via db_query (requires db.query:own capability) or inspect the SQLite file:

SELECT
  r.id,
  p.name AS persona,
  r.input_tokens,
  r.output_tokens,
  r.cache_read_tokens,
  r.cost_usd,
  datetime(r.started_at / 1000, 'unixepoch') AS started
FROM runs r
JOIN personas p ON p.id = r.persona_id
WHERE r.status = 'completed'
ORDER BY r.started_at DESC
LIMIT 20;

Cost by persona

To see where cost is accumulating:

SELECT
  p.name AS persona,
  COUNT(*) AS runs,
  SUM(r.input_tokens) AS total_input,
  SUM(r.output_tokens) AS total_output,
  ROUND(SUM(r.cost_usd), 4) AS total_cost_usd
FROM runs r
JOIN personas p ON p.id = r.persona_id
WHERE r.status = 'completed'
GROUP BY p.name
ORDER BY total_cost_usd DESC;

Cache efficiency

High cache_read_tokens relative to input_tokens means the provider’s prompt cache is working. This reduces cost significantly for personas with stable system prompts and large context windows.

Monitor the ratio:

SELECT
  ROUND(AVG(CAST(cache_read_tokens AS REAL) / NULLIF(input_tokens, 0)), 3) AS cache_hit_ratio
FROM runs
WHERE status = 'completed'
  AND started_at > (strftime('%s', 'now') - 86400) * 1000;

A ratio above 0.7 means 70% of input tokens are cache hits.

Budget limits

Per-persona budget limits are planned but not yet implemented. For now, monitor cost via the runs table and set external alerts if needed.