| name | token-dashboard |
| description | Read-only current-session and UTC-week token telemetry dashboard for Pi, Claude Code, Codex, and optional OpenRouter management analytics. |
| allowed-tools | Read,Bash(~/.agents/skills/token-dashboard/scripts/token_dashboard.py:*),AskUserQuestion |
| model-tier | economy |
| model | haiku |
| effort | medium |
| version | 1.0.4 |
| author | flurdy |
Token Dashboard
Show read-only token telemetry for the current session and current UTC calendar week. The week starts
Monday at 00:00 UTC. This skill has no /usage alias and does not modify transcripts or settings.
Usage
/token-dashboard # terminal dashboard; optional OpenRouter analytics when configured
/token-dashboard --offline # local telemetry only; guarantees no network
/token-dashboard --json # normalized schema v1 JSON
/token-dashboard --json --offline # machine-readable local-only report
/token-dashboard --session-id ID # explicitly select a known local session; the ID is never emitted
Resolve scripts/token_dashboard.py relative to this SKILL.md, then run the executable with the
user's arguments. Pi can load the managed Claude/Codex skill directory through its configured skills
path, and the collector remains compatible with Pi telemetry:
/path/to/token-dashboard/scripts/token_dashboard.py --offline
/path/to/token-dashboard/scripts/token_dashboard.py --json
Do not replace the collector with ad-hoc transcript reads or provider calls. Never call this skill
/usage.
Output contract
The final response must paste the collector's complete stdout verbatim in a fenced code block.
Do this even when the Bash tool card already contains the same output or Pi collapses earlier lines.
Do not summarize, paraphrase, reformat, truncate, or replace stdout with a success message. Preserve
all Current session, Week, and Sources rows, including unavailable and partial diagnostics.
Use a json fence for --json and a plain-text fence otherwise. Do not alter the block itself.
Analysis contract
After the verbatim block, add an Analysis section of two to four concise bullets (at most 120
words total):
- summarize current-session requests and recorded total; when both counters are available, identify
cache-read share as telemetry rather than cost;
- identify the largest week-to-date rows whose
total is available, without treating rows with an
unavailable total as zero;
- explain partial, estimated, or unavailable data using the reported source diagnostics; and
- mention one actionable setup issue, such as a missing OpenRouter management key, only when present.
Do not call high token volume good or bad without workload context. Do not describe local telemetry as
billing, spend, quota, or subscription allowance. Respect subset semantics: reasoning is already part
of output where marked, and cached input may already be part of input where marked. If the harness
requires a Next: line, append it after the analysis.
Setup and source authority
The stdlib-only collector reads these telemetry roots recursively:
- Claude Code:
~/.claude/projects/**/*.jsonl; only top-level assistant message.usage is
authoritative. Parent, subagent, and extra-agent transcripts are globally deduplicated.
- Pi:
~/.pi/agent/sessions/**/*.jsonl; official assistant-message usage is authoritative. Parent
sessions and linked nested child runs are deduplicated.
- OpenAI Codex:
~/.codex/sessions/**/*.jsonl; rollout event_msg/token_count cumulative counters
are authoritative and converted to duplicate-suppressed deltas.
- OpenRouter, optionally: Management Analytics API metadata plus one UTC-week query. Set
OPENROUTER_MANAGEMENT_API_KEY; an OPENROUTER_API_KEY is inference-only and is never sent.
The collector never reads auth files. It does not emit or persist credentials, prompts, responses,
tool output, raw transcript lines, session/message IDs, file paths, or raw API error bodies.
OpenRouter requests use the fixed https://openrouter.ai origin, reject redirects, bound response
size and timeout, and do not retry. --offline performs no network request even when a management
key exists.
See telemetry sources and authority for upstream evidence, retention,
authentication, period semantics, exactness definitions, and the prior-art decision.
Reading the report
Terminal output always has Current session, Week, and Sources sections. Generated and period
times use readable UTC labels. Each usage section states its scope, period, timezone, and selection once,
followed by a compact table containing source, harness, provider, model, agent, exactness, request count,
and nullable token counters. Source status
is tabular; complete diagnostics wrap below it. Control characters in displayed model and agent values
are replaced. Unavailable sources remain visible and do not make healthy sources fail.
JSON output uses normalized schema version 1 with:
generatedAt and periods for current-session and week;- UTC start/end boundaries, completeness, and current-session selection precision;
sources with status, exactness, detail, and authority;- flat
usage rows with nullable input, output, cacheRead, cacheWrite, reasoning, and
total counters, controlled unavailable reasons, and subset/exclusivity semantics.
Current-session selection uses --session-id when supplied. Otherwise it detects an active Pi,
Claude Code, or Codex harness from supported runtime environment evidence and selects only that
harness. Pi parent and nested child-run sessions are linked by their official directory layout and
parentSession metadata when present. Without active-harness evidence, only the single globally
newest local session is selected and labelled estimated; unrelated per-harness sessions are not
combined.
Limitations
- Local JSONL telemetry is not provider billing, subscription quota, or an authoritative allowance.
Claude, Pi, and Codex subscription allowance can be unavailable.
- OpenRouter analytics is API telemetry for returned metrics, not subscription quota. Metric
availability is negotiated from the live metadata response; truncated or skipped rows are partial.
- Missing counters stay
null; the collector does not invent zero. Claude does not record reasoning
or a portable total in the accepted usage rows. Pi reasoning is a subset of output. Codex cached
input and reasoning are subsets of input and output respectively.
- Malformed or oversized rows, missing timestamps, incompatible duplicate snapshots, rejected
symlinks, read failures, missing roots, network failures, and sanitized 401/403/429 responses
degrade only the affected source.
- Version 1 supports UTC only and offers no timezone option.
Maintainer validation
python3 -m unittest discover -s skills/token-dashboard/tests -p 'test_*.py' -v
make validate-skills
make test-validate-skills
make clean-code
Tests use temporary telemetry roots and mocked OpenRouter requests; they send no real network
traffic and contain no live credentials.
