docs / configuration

Configuration

Watch folder

TokensLab tails JSONL session logs. Claude Code writes them under ~/.claude/projects. Change the folder from the header (“Change folder”) or Settings. A rescan reads only bytes appended since the last ingest cursor — it does not re-parse the whole tree.

Daily budget

Set a daily cost threshold in the header. Crossing it raises a notification once per calendar day. The number is cache-aware, so it matches the invoice much closer than a raw token sum.

Theme and language

Light, dark, and system. Interface strings ship in English, Portuguese and Spanish. The same locales are on this site (EN / PT / ES in the nav).

Notifications

Idle (dead) sessions, budget crossings and ingest errors can notify through the OS. Opening the app does not replay months of history: the first pass records what already exists and stays quiet, except for “you are already over budget today.” Five sessions going idle in the same pass fold into one notification, led by the costliest. You can mute kinds in Settings. The default idle threshold is 30 minutes.

What TokensLab does not do

• No account, no cloud sync, no telemetry.
• No outbound network from the desktop app.
• Phase 1 prices Claude Code. Cursor, Codex and Gemini sit on the tray; their local stores do not always keep token counters, so we will not invent a dollar amount.