tokenstat help

Guides and how-tos

Install the app or CLI, read your usage, sync a machine, and publish a profile. Short, practical guides.

Getting started

4 guides

Learn what tokenstat reads, where its numbers come from, how to install it on macOS, Linux, or Windows, and how to remove it.

What tokenstat counts, and how to read the numbers

Token totals, estimated API value, subscription coverage, and confidence labels explained, with links to source-specific limits.

What tokenstat reads, stores, and connects to

Usage collection, repository content, vendor credentials, and remote connections have different data boundaries. Here is what each feature handles.

Install the tokenstat CLI on macOS, Linux, or Windows

Install commands, setup defaults, hourly collection, automatic updates, and options for local-only use.

Uninstall tokenstat

One line to remove the schedule and the binary, one flag to delete your archive too, and the manual steps if you would rather do it by hand. Nothing is left behind that this page does not name.

Desktop app

6 guides

Use the macOS app with the same local archive as the CLI. Learn what each screen shows, how workspaces run agents beside their diffs, and what the app sends to your dashboard.

Set up the tokenstat desktop app

Install the Mac app, add a repository, start a chat or a terminal with an agent, and find your usage reports. Local work needs no tokenstat account.

Run agents in a repository

Add a folder as a repository, start a chat or a terminal with an agent, hand a chat to another agent, and review what changed before anything is committed.

Plan limits on your dashboard

The app can tell your account how much of each plan window you have used, so the website shows the same figure as the window on your desk. What travels is a percentage and a reset time, nothing about what you ran.

Keep a Mac or Linux host available for remote work

Install the host, keep it running, approve devices, and troubleshoot remote access from another computer or phone.

Set up remote screen access

The checks, permissions, and per-device approval needed to view or control another screen.

Encrypted SSH vault and recovery

How tokenstat syncs SSH hosts, keys, and snippets without receiving the keys needed to read them.

CLI and MCP

3 guides

Find the right command for each question, add usage to your shell prompt, set a spending cap, or connect an agent to usage, workspaces, tasks, notes and jobs through MCP.

Which tokenstat command shows what

One archive, a dozen views over it. Which command answers which question, the four filters that work on all of them, and why every report can be piped as JSON.

Set a budget and put usage in your prompt

Two commands built for glancing rather than reading: a soft list-rate cap you can check at any time, and a single line you can hang off your shell prompt without slowing it down.

Connect an agent to workspaces, tasks and notes with MCP

Connect tokenstat's 53 MCP tools for charts, usage, workspaces, tasks and jobs.

Reading your usage

3 guides

Most tokens are cache reads, which cost less than fresh input. Learn how to read token totals, context size, and the published API price.

Why cache reads dominate your token count

Most of your tokens are cache reads, and they cost a fraction of fresh input. That is why a raw token number tells you almost nothing, and why a big context is not the expense people assume.

How sure each usage number is

Each event is exact, strong, or derived. That says whether the next scan can recognise the same event. The token count itself was read from the log.

Where model prices come from

How the tokenstat model catalog is built: three public price feeds, list rates I check by hand, the merge rules, where benchmark scores come from, and how to report a wrong number.

Sync and profiles

3 guides

Sync is optional, and accounts are private by default. Learn what leaves your machine and what publishing a profile makes visible.

What leaves your device when you sync usage

The usage-sync fields, hashed project keys, schema versions, and the command to inspect a proposed upload.

Publish a profile, or stay private

An account is private until you deliberately publish it. Here is what claiming a handle does, what a public profile shows, and how to go back to private without losing anything.

Put your usage on a README, a forum or your site

Cards for a GitHub README, PNG banners and userbars for forum signatures, and a script widget for your own site. All of them keep working when you change your handle, and none of them asks the server more than once an hour.

Tools and sources

2 guides

See which coding tools tokenstat reads, where they store usage, and which gaps cannot be filled.

Supported tools, collection, and launch requirements

Compare local usage collection, agent launch support, vendor connections, and plan-limit readings for supported tools.

Cover Cursor and Antigravity, the tools that need a login

Set up Cursor and Antigravity. In these commands, token means the vendor login, not a counted usage token.

Troubleshooting

3 guides

An empty report, a machine that stopped syncing, or a total that disagrees with a vendor's billing page. Each guide names the likely cause first and the fix second, in the order worth checking.

tokenstat found no sessions

An empty report almost always means the logs are somewhere tokenstat did not look, or were never written. Here is how to tell which, in the order worth checking.

Why your numbers disagree with a vendor's dashboard

tokenstat counts a different thing from a billing page, over a different window, from a different source. Here is which differences are expected and which are worth reporting.

A device stopped syncing

A profile that stopped updating is usually a paused schedule, a revoked token, or a device limit. Here is how to tell which, and what to do about each.