From local logs to your first dashboard

Requirements

• Python 3.9 or newer.
• macOS, Linux, or Windows.
• At least one supported CLI has produced local logs.

Clone and run

git clone https://github.com/LingXi-fur/tokens.git
cd tokens
./run doctor
./run serve --open

This source-checkout path is the verified public setup. A package-registry release is not required.

Optional local command install

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
tokens --version

On Windows PowerShell, activate with .venv\Scripts\Activate.ps1. The local install also resolves the Windows-only tzdata dependency.

Check the environment

tokens doctor

The doctor reports timezone, output and cache permissions, and candidate file counts for each source. It does not parse messages or print project and session identifiers.

Open the live dashboard

tokens serve --open

The server binds only to 127.0.0.1, checks local log changes every five minutes by default, and updates the open page without uploading data. The page can switch between 1, 5, 15, or 30 minutes, or pause refresh. Press Ctrl+C to stop it.

For an offline archive instead, generate a self-contained file:

tokens dashboard --output ~/Reports/tokens --open

If a browser cannot be opened automatically, the CLI prints the local URL or generated path.

Choose sources

Claude is the only default source, which keeps the initial scan narrow. Repeat --source to combine tools:

tokens dashboard \
  --source claude \
  --source gemini \
  --source codex

Use --timezone Europe/Berlin to override the detected system timezone for a run.

Create a safer sharing copy

tokens dashboard --anonymize \
  --since 2026-08-01 \
  --until 2026-08-31

Continue with the CLI reference, dashboard guide, or privacy guide.