Local-first is not the same as safe to publish
tokens does not upload logs. A generated HTML file can still copy sensitive local metadata into an easy-to-share artifact.
What does not leave the machine
The CLI uses no hosted backend, account, telemetry endpoint, remote script, CDN, or runtime analytics service. Reading, aggregation, cache, and report generation happen locally. tokens serve uses HTTP only on 127.0.0.1; it does not bind to the LAN or send logs to an external service.
This statement applies to tokens itself. Your AI coding tools may have their own network and retention policies.
Read locations
| Source | Default path | Default? |
|---|---|---|
| Claude Code | ~/.claude/projects/**/*.jsonl | Yes |
| Gemini CLI | ~/.gemini/tmp/*/chats/session-*.json | No |
| Codex | ~/.codex/sessions/**/rollout-*.jsonl | No |
| Optional Claude Code Router | ~/.claude-code-router/custom-router.js | Only when present |
tokens doctor counts candidate readable files but does not parse messages or print identifiers.
The optional router file is read locally as text and is never executed or uploaded. A deliberately limited parser uses it only to interpret plain Claude tier request aliases. Router rules never change Gemini or Codex model names. Unsupported JavaScript remains uninterpreted.
Cache and output
Reports default to ./out. The parsed-file cache is separate and lives in the platform user cache directory:
- macOS:
~/Library/Caches/ai-cli-tokens/ - Linux:
$XDG_CACHE_HOME/ai-cli-tokens/or~/.cache/ai-cli-tokens/ - Windows:
%LOCALAPPDATA%\ai-cli-tokens\
The cache contains normalized derivative records and should be treated as sensitive local data. Use --no-cache to force a re-read; deleting the cache is not required for normal use.
What reports can contain
Terminal report
Aggregated period totals, model columns, and call-record counts printed to the terminal.
Static HTML
Aggregated trends, model and source distributions, details, generation time, and selected sources.
Interactive dashboard
The regular dashboard may embed more than the rows visible on screen:
- Exact dates, models, sources, hourly values, and token composition.
- Complete daily project aggregates with full working directories where available.
- Complete daily session aggregates with identifiers and derived titles where available.
- Per-turn token sequences for attributable sessions, capped at the most recent 200 turns per session.
- Aggregate project → model and model → session relationships.
- Optional titles from a local sidecar or the first suitable user text.
dashboard.html to a public issue, static site, drive, or chat without inspecting it.What --anonymize changes
The pseudonymized report replaces complete project paths, display paths, raw session identifiers, sidecar summaries, and derived natural-language titles before they enter report aggregates. Stable aliases preserve in-report interaction. A fresh random key is used for each generated report and is not stored in the HTML or cache.
It still retains exact dates, token values, hour patterns, model names, source labels, aggregate relationships, and replay sequences. Model names and router-resolved backend names are not pseudonymized. A backend name can reveal details of the user's local routing configuration. Custom model names can contain organization semantics, and activity patterns can be identifying.
Browser state boundaries
Data Trail steps, temporary model clues, Signal Dock preview and pin state, Exactness Key state, held comparison, and selected project/session entities exist only in current page memory. They do not create new localStorage keys or add entity identifiers to a view URL.
A pinned previous-period comparison can enter the URL as compare=1. Existing view links can also contain granularity, global model selection, focus date, and theme. They do not contain cwd, raw session IDs, or token details.
Local achievements and Token Almanac store compact, identity-free snapshot summaries in localStorage. They do not store cwd, session IDs, titles, aliases, message text, or per-turn sequences. Exported Almanac JSON still contains exact dates, model names, and token values.
Safe sharing checklist
- Prefer a terminal screenshot or synthetic visualization.
- Use
tokens dashboard --anonymize. - Restrict
--sinceand--until. - Confirm you selected
dashboard-anonymized.html, not the regular report. - Search for usernames, home paths, customers, repositories, session identifiers, summaries, and custom model names.
- Assess whether exact dates, hourly activity, and replay shapes are appropriate for the recipient.
- Never attach raw logs to a public issue.
The documentation and README preview use synthetic values and are tested for common local path, username, UUID, and session-ID leaks.