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, workspace 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 project folder, launch an agent, and find your usage reports. Local work needs no tokenstat account.

Run agent sessions in a workspace

A workspace is a folder with a file tree, a git history, and a session launcher. Here is how to add one, start an agent in it, run several at once, and review what they 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 49 MCP tools, copy a short agent prompt, discover workspace IDs, and answer tokenstat questions from MCP.

Reading your usage

2 guides

Most tokens are cache reads, which cost less than fresh input. Learn how to interpret token totals, context size, and list-rate costs.

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 confident is each number, and what confidence actually means

Every event carries exact, strong, or derived. It is a statement about identity and double counting, not about arithmetic, and knowing the difference tells you which totals can drift.

Sync and profiles

2 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.

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 sources that need a token

Set up Cursor usage fetches and Antigravity IDE collection, inspect authentication status, and remove a stored vendor 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.