Set up the tokenstat desktop app
The CLI is the engine; the desktop app is a window over it. Both read the same local archive, so the heatmap in the app and the heatmap the terminal prints are the same picture, and both run entirely on your device.
This page gets it onto your machine and tells you where things are. For the full tour of what the app can do, read the desktop app.
Install it
Download the disk image, drag the app to Applications, and open it:
It needs macOS 14 or newer. It is a universal binary, signed and notarized, so Gatekeeper opens it without an argument.
You do not need the CLI as well. The app carries the same engine, and installing one does not install the other. Many people run both, because they answer the same questions in different places, and they share one archive so the numbers never disagree.
First run
The app scans on open, so the first thing it shows you is your own history rather than an empty state. If it finds nothing, that is almost always the logs being somewhere it did not look, and tokenstat found no sessions works through the reasons in the order worth checking.
Nothing has left your machine at this point, and nothing will until you sign in and ask it to. Signing in is under the account menu, and it uses a device code rather than a password: the app shows an eight-character code, you approve it at tokenstat.ai/link, and that is the whole pairing.
Where things are
| Screen | Answers |
|---|---|
| Home | What is left before you start: the heatmap, today and this week, plan limits, anything running now |
| Insights | What you spent: daily volume, top models, breakdowns by harness and project |
| Workspaces | The work itself: file tree, git history, and agent sessions on their own tabs |
| History | Uncommitted changes, with a real diff per file and a commit box |
| Machines | Every machine on your account, and the workspaces on each |
| Browser | Your own pages on tokenstat.ai, inside the app |
A workspace carries more than its sessions. Tasks is a board where a card is a job an agent can pick up, Workflows wires agents, commands and approvals into one graph, Automations runs a job on a schedule and keeps the result of every run, and Notes is the scratch pad that survives the session that wrote it. The desktop app has a picture of each.
Clicking a day on the Home heatmap opens what it was made of, model by model. The Insights inspector does the same for any row in any table.
Light and dark
Every screen ships in both themes and follows the system setting. The screenshots on this site are the dark ones because that is what most people work in, not because the light theme is an afterthought.
Related
- The desktop app is the full tour: every surface, what it is for, and what is still being built.
- Run agent sessions in a workspace is the part most people came for.
- Plan limits on your dashboard covers the one setting that sends anything to the website.
- Which tokenstat command shows what is the same ground, in the terminal.
More in Desktop app