GETTING STARTED

From local logs to your first dashboard

No database, service process, frontend build, or account is required.

Requirements

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
tokens doctor
tokens demo --open
tokens serve --open

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

Check the environment

./run 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.

Explore with synthetic data

No install yet? Open the hosted synthetic Demo. It runs the real Dashboard in your browser with generated records only; no account, local logs, or upload is involved.

After cloning, create the same private local experience:

./run demo --open

This writes out/dashboard-demo.html through the real dashboard pipeline using generated sample data only. It does not read local Claude Code, Gemini CLI, or Codex logs.

Open the live dashboard

./run 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:

./run 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:

./run 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

./run dashboard --anonymize \
  --since 2026-08-01 \
  --until 2026-08-31
Pseudonymized is not anonymousThe generated file still contains exact dates, models, token values, relationships, and replay sequences. Inspect it before sharing.

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