token-dashboard

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.