# Token Dashboard > Read-only current-session and UTC-week token telemetry dashboard for Pi, Claude Code, Codex, and optional OpenRouter management analytics. - Skill: `flurdy/token-dashboard` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add flurdy/token-dashboard` - Raw SKILL.md: https://api.skillmd.com/api/skills/flurdy/token-dashboard/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: flurdy (https://skillmd.com/u/flurdy) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/flurdy/token-dashboard --- # 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 ```text /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: ```bash /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 `SECRET_API_KEY_PROJECT` and store `openrouter_management` with `secret-api-key`; an explicit `OPENROUTER_MANAGEMENT_API_KEY` remains supported. `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](references/sources.md) 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. ## See also - `/pi-spend` for Pi's recorded per-response cost estimates by day, week, and month. Cost is out of scope here by design: only Pi records it, and this skill stays token-only across all four sources. ## Maintainer validation ```bash 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.