What tokenstat reads, stores, and connects to
Local usage reports need no tokenstat account. The usage collector reads supported tool records and stores counters with local metadata. The desktop workspace can also open files and conversations, run agents, and connect to other machines. Those features handle more than token counts.
Usage collection
Session records can contain prompts, replies, and code alongside token counts. The collector opens those records, extracts usage, and leaves conversation text out of the usage archive.
The local usage archive does retain project labels or paths, session identifiers, model identifiers, timestamps, and counters. Local reports use those names so you can recognize your projects. A copy of the archive can therefore reveal usage and project metadata even though it does not contain the original conversation text.
The tokenstat-core crate handles parsing and aggregation without a network stack. This boundary applies to that crate, not to every feature in the CLI or desktop app.
Workspace files and conversations
Workspace features open the project files, terminal output, and conversation records needed to display your work. Chat and work search can read conversation content. The usage archive's exclusion of conversation text does not mean the rest of the app cannot read or display it.
Agents run with their configured permissions and connect to their own providers. An agent may read files, send context to a model, run commands, and change Git state. Review the agent's settings before launching it. tokenstat's Git review UI does not impose a separate restriction on every command an agent can run.
Vendor credentials and network requests
Local usage collection and connected features have different requirements:
| Feature | Connection or credential use |
|---|---|
| Reading supported records on disk | No tokenstat account or upload required |
| Cursor usage | Uses a vendor credential to request aggregate usage |
| Plan-limit readings | May use available vendor credentials or local tool services, depending on the tool |
| Antigravity IDE collection | Connects to the running app's local service |
| Updates, prices, and model catalog | Fetches release or reference data. Setup enables scheduled updates by default |
| Agent sessions and workflow steps | Connect to the providers or services configured for that work |
| Browser and SSH | Connect to the pages or hosts you open |
The software does not send usage telemetry for advertising. See the privacy notice for the website's operational measurements, account data, and connection metadata.
Optional usage sync
Linking an account lets you combine usage across devices. Usage sync sends daily aggregates and metadata, with project paths replaced by keyed hashes. The sync payload excludes prompts, replies, code, project paths, and session identifiers.
Inspect the usage payload with:
tokenstat sync --dry-run
This prints the proposed usage upload without sending it. It describes usage sync, not every other network feature. See the field reference.
Remote connections
Remote access is enabled separately on a host. Signing in on another device does not grant that device access to the host's work. Approve it on the host, or redeem an invitation code generated there.
Remote traffic is encrypted between device identities. tokenstat tries a direct connection first. A relay forwards encrypted traffic when needed. The service processes connection metadata and relay usage even though it cannot decrypt session content. Screen viewing and control require separate permissions.
See host setup, screen access, and the privacy notice for details.
Check the implementation or report a problem
The software source is available for review. For a security issue, use the repository's Security Advisories rather than a public issue.
More in Getting started