Project site · Download · Product tour · Providers · Changelog · Build · CLI
A Windows tray app for keeping track of AI coding usage. See your tokens, known cost, and available quota in one place, then open the report when you want the detail. The CLI exposes the same local data for scripts and diagnostics.
No TokenUsage account is required. Provider data stays local unless you enable a documented opt-in connection.
Important
The current release is an unsigned Windows x64 portable preview. Download preview 5. Provider coverage depends on the tool, account, and available data source.
- Fast tray view — check today's usage, the period, the per-agent breakdown, and quota.
- A report that answers questions — will each quota last to its reset, why usage changed from the previous period, and how much work each quota point covered across recent resets.
- Multiple accounts — show separate quotas for code-swap (Codex) and claude-swap (Claude) profiles.
- Honest data states — reported, estimated, partial, stale, unavailable, and unpriced values remain distinct.
- Stable CLI output — read reports, limits, and diagnostics as human text or versioned JSON.
- Local-first and English-only — keep the interface predictable without indexing conversations or commands.
Today's and the last 30 days' tokens, spend by tool, and each quota with its reset.
Choose 7, 30, or 90 days. Each period is compared with the one before it.
- Summary — tokens, approximate spend at API list prices, daily average, and how many quotas run out before their reset at the current pace.
- Will it last to the reset? — used quota across each daily or longer window, with earlier cycles in gray and a dashed projection that stops where the quota runs out.
- Tokens per day — stacked by agent, with the previous period as a dashed line.
- Why did it change? — a waterfall from the previous total to the current one through the agents and models that changed most.
- Recent resets — used quota, cycle tokens, and tokens per 1% for the last four cycles of each quota.
- Detail — tokens, change, spend, share, and active days by agent, model, or day.
The share button saves the whole report as one image. In Options > Appearance, choose rings, bars, or numbers only for compact limits. Rare options live in Options > Advanced.
These captures use synthetic sample data and contain no account data. The banner mascot is an illustration generated with imagegen.
TokenUsage reads twelve tools. Each one has a bounded local reader.
| Provider | Local usage | Cost | Live quota |
|---|---|---|---|
| Codex | Yes | Reported or estimated | Yes, through the official local app-server |
| Claude Code | Yes | Reported or estimated | Yes, opt-in account usage (5-hour, weekly all models, and named model limits) |
| Cursor | Yes, partial | Estimated when the model matches | Not available through the current contract |
| Grok Build | Yes | Reported or estimated | Not available through an approved interface |
| ZCode | Yes, counters per request | Estimated when the model matches | Not available through an approved interface |
| OpenCode | Yes | Reported or estimated | No common quota source |
| Antigravity | Yes, experimental | Estimated | Blocked by policy |
| Amp | Yes, partial | Credits stay separate from USD | No stable public source |
| Mux | Yes | Reported | No common quota source |
| Goose | Yes, partial | Estimated when pricing exists | No common quota source |
| Hermes | Yes, partial | Reported or estimated | No common quota source |
| GitHub Copilot | Yes, VS Code chat sessions, partial | Recorded AI credits before plan allowances | No remaining-quota source |
See the provider matrix for sources, limits, and publication gates.
TokenUsage never creates fake activity. Missing data appears as missing data.
Each provider adapter reads the smallest approved source that can answer a usage question. Sources include official local APIs, bounded numeric logs, and read-only aggregate database queries.
TokenUsage keeps these values separate:
- provider-reported cost
- cost estimated from known model pricing
- tokens without a known price
- coverage and freshness
- quota remaining and reset time
- observed local usage.
An API-rate estimate is not a subscription invoice. A local usage total is not a remote account quota.
- No prompt, response, conversation, command, tool call, email, or account identifier enters usage storage.
- TokenUsage does not copy another application's session token or read its credential store.
- Local API access and telemetry stay off by default.
- Logs, diagnostics, fixtures, issues, and pull requests must not contain credentials or customer content.
Read SECURITY.md before reporting a vulnerability.
The portable preview runs on Windows x64 and includes its .NET and Windows App SDK runtimes. You do not need a separate .NET installation. The app targets Windows 10 version 1809 or later. This preview has been checked on Windows 11; clean-machine qualification is still pending.
Building from source also requires the .NET 10 SDK, Visual Studio with MSBuild and Windows app packaging tools, and Windows SDK 10.0.26100.0. Source builds support x64 and ARM64; this release includes x64 only.
Download v0.0.1-preview.5, extract the ZIP, and open TokenUsage.App.exe.
This preview is unsigned and portable-only. Windows may show a publisher or SmartScreen warning. It has no MSIX installer and is not delivered by automatic updates. See the release notes for fixes and limits.
The portable ZIP contains the app and CLI. Run tokenusage.cmd from its root to use the CLI.
Both executables use the Data folder beside the app executable.
Keep TokenUsage.portable in the extracted folder. Move the complete folder when you move or update the portable app.
The MSIX and portable builds use separate data folders. Installing one build does not delete or import data from the other build.
Read the release procedure for build, signature, and publication details.
In Options → General, enable automatic updates to check GitHub once every 24 hours while TokenUsage runs. Startup checks respect the same interval. Updates are off by default. You can also check and install manually. Only newer stable releases for your architecture are accepted; downloads must pass GitHub SHA-256 and size verification.
Portable updates apply after exit and preserve the Data folder. Direct MSIX updates also require a trusted package signature and Windows 10 version 2004 or later. Store installations use Microsoft Store updates; development builds do not self-update. Builds released before this updater need one manual upgrade.
Build from PowerShell at the repository root:
.\BuildAndRun.ps1 src\TokenUsage.App\TokenUsage.App.csproj -SkipRun /p:Platform=x64Build and launch with package identity:
.\BuildAndRun.ps1 src\TokenUsage.App\TokenUsage.App.csproj -Detach /p:Platform=x64The helper launches the packaged app through winapp. Do not run the packaged executable directly.
Run the complete local gate before requesting review. It runs the five test projects on the x64 host, excludes opt-in integration tests, and builds the package and its production dependencies:
.\scripts\check.ps1 -Platform x64 -Configuration ReleaseUse -Platform ARM64 for a cross-architecture package build. Tests still run on the x64 host.
For focused checks and the runtime evidence each change needs, use the contributor testing guide.
For a quick dependency and security pass on active projects:
.\scripts\deps-check.ps1
.\scripts\audit.ps1The repository uses the .NET SDK and MSBuild.
Install the package and enable its execution alias. Then run:
tokenusage refresh
tokenusage report --days 30 --format human
tokenusage report --from 2026-07-01 --to 2026-07-31 --agent codex --format json
tokenusage limits --format json
tokenusage doctor --format human
tokenusage pricing audit --format human
tokenusage pricing refresh --dry-runPricing evidence keeps direct API rates separate from host-specific rates. The weekly refresh checks only allowlisted official pages and never stores their content or edits a price. See pricing evidence and refresh.
Run tokenusage refresh before a report when the app has not updated the local store. Refresh writes normalized numeric records from installed providers.
The JSON contracts use versioned names such as tokenusage.report.v1, tokenusage.limits.v1, and tokenusage.doctor.v1.
- Documentation index
- Provider matrix
- Contributor testing guide
- Release procedure
- Maintenance dependency notes
| Path | Responsibility |
|---|---|
src/TokenUsage.App |
WinUI views, view models, and application composition |
src/TokenUsage.Core |
Portable domain, storage, cache, and coordination contracts |
src/TokenUsage.Providers |
Provider adapters and pricing support |
src/TokenUsage.Presentation |
Shared dashboard and report presentation |
src/TokenUsage.Platform.Windows |
Windows integration |
src/TokenUsage.Runtime.Windows |
Shared Windows runtime composition |
src/TokenUsage.Cli |
Commands and stable JSON output |
src/TokenUsage.Package |
MSIX manifest and packaged payloads |
tests |
Architecture, core, provider, platform, app, and CLI tests |
Contributions and pull requests are welcome.
Open an issue before writing the change. Every pull request must link its issue and stay within the agreed scope.
Provider contributions need reproducible evidence. This rule is especially important when maintainers cannot access the provider. A mock fixture alone does not prove a real integration.
Read CONTRIBUTING.md and the contributor testing guide before starting.
The provider catalog and documentation structure take inspiration from OpenUsage, CodexBar, and CodeBurn. TokenUsage adapts those ideas to a native Windows app with its own privacy and evidence rules.
These projects do not endorse TokenUsage. Provider names and marks belong to their owners.
TokenUsage is available under the MIT License. Third-party material and terms appear in THIRD-PARTY-NOTICES.md.


