Skip to main content

Analytics & Tokens

Track token usage, model distribution, cache efficiency, and estimated cost across all sessions.

Overview

CodePiper tracks token usage from every Claude Code session and aggregates it into dashboards and CLI reports. This gives you visibility into how much your agents are consuming, which models they’re using, and how well caching is working.

Analytics data comes from Claude Code transcript tailing. The daemon parses JSONL transcripts in real time, extracting token counts per request. Codex sessions have limited analytics (PTY output only, no token-level data).

What’s Tracked

MetricDescription
Prompt tokensTokens sent to the model (input)
Completion tokensTokens generated by the model (output)
Cache creation tokensTokens written to the prompt cache
Cache read tokensTokens served from the prompt cache
Total tokensSum of all token types per request
ModelWhich model handled the request
Tool usageWhich tools the agent invoked and how often

Cache Hit Rate

Cache hit rate measures how effectively prompt caching is reducing your token costs:

cache_hit_rate = cache_read_tokens / (prompt_tokens + cache_creation_tokens + cache_read_tokens)

A high cache hit rate (70%+) means most of your input tokens are being served from cache, significantly reducing both latency and cost on cached models.

Cost Estimation

CodePiper estimates costs using per-model pricing tables:

  • Each request’s tokens are multiplied by the model’s per-million-token rates
  • Separate rates for input, output, cache write, and cache read
  • The estimate covers all supported Claude models (Opus, Sonnet, Haiku across versions)

Cost estimates are approximate. Actual billing depends on your Anthropic plan and any volume discounts.

Dashboard Views

The Analytics page in the web dashboard shows:

Token Usage Over Time

A time-series chart showing prompt, completion, cache creation, and cache read tokens per day. Filter by range: today, 7 days, 30 days, or all time.

Model Distribution

Breakdown of token usage by model. Shows which models your sessions are spending the most tokens on, helping you optimize model selection.

Activity Timeline

Daily message counts (user and assistant) across all sessions. Useful for understanding usage patterns and peak activity.

Tool Usage

Top 15 most-used tools across all sessions. Extracted from assistant message events in transcripts.

Sessions by Provider

Distribution of sessions between Claude Code and Codex.

CLI Reports

Terminal window
# Overview with cost estimate
codepiper analytics
codepiper analytics overview --days 7


# Token breakdown by model
codepiper analytics tokens --days 30


# Top tools used
codepiper analytics tools --days 7


# Daily activity timeline
codepiper analytics activity --days 30


# Sessions by provider
codepiper analytics sessions

The --days flag accepts 1 (today), 7, 30, or 0 (all time).

Data Pipeline

The analytics pipeline works as follows:

  1. Claude Code writes JSONL transcript entries as the session runs
  2. The TranscriptTailer reads the file with byte-offset tracking (crash-safe, no data loss on restart)
  3. Token counts, model info, and tool usage are extracted from each entry
  4. Data is persisted to the token_usage and events tables in SQLite
  5. The analytics endpoints aggregate this data with SQL queries filtered by time range

All processing happens locally. No data leaves your machine.

What’s next