Start with doctor, source, and range

Why does tokens say no logs were found?

Run:

tokens doctor

Claude is the only default source. If you only use another tool, select it explicitly:

tokens day --source gemini
tokens day --source codex

The installed CLI and the logs must also belong to the same user account unless paths are customized in code.

Why do the README commands start with ./run?

The verified public path runs directly from a cloned source checkout, so it does not depend on an unverified package-registry release. If you want a global-looking tokens command inside a virtual environment, install the checkout locally with python -m pip install -e ..

Which timezone defines a day?

The detected system local timezone. Override it for a run with an IANA name:

tokens dashboard --timezone Asia/Tokyo

An unknown timezone is rejected instead of silently falling back.

Why did a changed log not update the dashboard?

An exported dashboard.html is a generation-time snapshot; refreshing the browser cannot rerun Python. Keep a live view open with:

tokens serve --open

Live mode checks file modification time and size every five minutes by default. The open page can choose another preset or pause refresh. Re-run an offline export when you need a newer archive.

Does --open work across platforms?

It uses the Python standard library to open either a file URL or the loopback live URL in the default browser on macOS, Linux, and Windows. If opening fails, an export remains valid and a live server keeps running; the path or URL is printed.

Is an anonymized dashboard safe to publish?

Not automatically. It is pseudonymized: exact dates, models, token values, relationships, and replay sequences remain. Restrict the date range and inspect the file before sharing.

Why can the dashboard be large?

It is one self-contained file with data, styles, scripts, aggregates, and retained session token sequences. A longer range and more attributable entities increase size. Use --since and --until to reduce it.

Does it contain complete message text?

Per-turn replay stores token values, not full per-turn text. A regular report can still contain a natural-language session title derived from a sidecar or suitable first user text. --anonymize skips those titles.

Still stuck?

Open an issue with the command, operating system, Python version, and sanitized error output. Do not attach raw logs or an unreviewed dashboard.