docs / how it works

How it works

TokensLab never asks for an API key and never phones home. The installer ships a rate card and a local database. The only input is files already on disk.

The pipeline

~/.claude/projects/**/*.jsonl
   → watch the folder (debounced ~1s)
   → read only bytes appended since last time
   → parse assistant turns
   → price against the shipped rate card
   → store sessions and turns locally
   → dashboard

A full rescan of 66 MB of logs is how a cost monitor becomes a cost. The ingest cursor stores a byte offset per file and only reads what was appended.

Pricing

Each turn is priced with five counters: plain input, output, cache creation (5-minute and 1-hour writes) and cache read. Models missing from the card are unpriced — the total is labelled a lower bound, never a fiction of zero.

What you see

• Dashboard — today, all-time, burn rate, projected month, live vs idle.
• Sessions — every conversation, filterable, with the same cache-aware dollars.
• Graph — files the model touched, sized by cost.
• Skills — prompts, tools and context packs that actually appear in the logs.

There is no public HTTP API. The desktop app talks to its own local store. If you need team workspaces or audit logs, that is Enterprise — email hello@tokenslab.com.