v1.0.0 to v1.0.3

34 added, 8 removed. Audit A to A.

---

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: low

- version: "1.0.0"

+ effort: medium

+ version: "1.0.3"

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

```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. Render its output as-is,

- including unavailable and partial source diagnostics. Never call this skill `/usage`.

+ 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](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. Every usage row

- names its scope, source, harness, provider, model, agent, period/timezone, exactness, request count,

- and nullable token counters. Control characters in displayed model and agent values are replaced.

- Unavailable sources remain visible and do not make healthy sources fail.

+ Terminal output always has **Current session**, **Week**, and **Sources** sections. 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

```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.