Quotas & reset windows
Track session, weekly, monthly, and model-specific limits, with reset timestamps and remaining capacity where available.
USAGESTAT / THE BACKEND
Your providers.
Your building blocks.
A scriptable CLI, local dashboard, and HTTP API. Bring your AI quotas, tokens, and costs together, then use the numbers wherever you work.
Rustcore & daemon
77provider plugins
MITlicensed
UsageStat · sample session
Choose an example or type a command below.
usagestat usage codex claudeCodex · Plus Session ██░░░░░░░░ 24% used Weekly ████░░░░░░ 38% used Claude · Max Session ████░░░░░░ 42% used Weekly ███████░░░ 67% used Sonnet ███░░░░░░░ 31% used
v1.0.3 + source
This guide covers the current backend. The dedicated History tab, doctor, and native /v1/limits exports require the source/dev build and are pending the next package release.
KNOW WHAT’S LEFT. SEE WHAT YOU’VE USED.
Different providers.
A consistent picture.
Provider plugins turn different account endpoints into shared progress meters, text metrics, badges, and charts. Each integration reports the information its provider makes available.
Credits & balances
Read subscription credits, prepaid balances, spend, overages, and provider-specific budgets without opening every account dashboard.
Tokens & local costs
Get Claude and Codex token/cost summaries through pinned ccusage runners. Provider plugins also expose token and spend metrics when supported.
Usage pace
Where a provider reports a quota window and its duration, compare actual usage with the expected pace and estimate whether the quota will last until reset.
Provider status
Check supported status pages on demand, or include provider service status alongside a usage probe.
Independent sources
Configure named provider instances for supported account/source combinations. Keep web subscriptions, API access, and custom commands distinguishable.
Local costs can be API-equivalent estimates rather than billed amounts. The first cost scan can download a pinned ccusage package through an available JavaScript package runner.
A GOOD CITIZEN IN YOUR TERMINAL.
Check it.
Pipe it. Script it.
Run a one-off probe without starting the daemon. Request several providers in one command, save snapshots to JSONL, and export the result into the rest of your workflow.
- Text for a quick glance. Read usage and provider status directly in your terminal.
- JSON for automation. Consume structured snapshots and command results.
- CSV for analysis. Export live usage or select providers from saved history.
- Predictable controls. Configure paths, polling, and per-provider probe timeouts.
usagestat usage claude codex
usagestat --json usage claude
usagestat usage claude --save
usagestat export claude --format csvusagestat status claude codex
usagestat cost claude codex| Command family | What it does |
|---|---|
usage / probe | Query one provider, several, or all enabled providers. Save snapshots or include provider status. |
list | Discover provider plugins, enabled state, icons, and declared UI metadata without contacting provider APIs. |
status | Read supported provider status pages independently of a usage probe. |
cost | Read Claude and Codex local token/cost summaries through pinned ccusage runners, or summarize saved history. |
export | Export live snapshots or provider-filtered JSONL history as JSON or CSV. |
daemon | Enable, disable, check, and configure the background daemon and optional T3 bridge. |
dashboard | Open the local dashboard or print its URL for a remote shell. |
config validate / dump | Check configuration and inspect its normalized representation. |
plugin validate | Validate discovered provider plugins and configuration. |
cache clear | Clear saved snapshots or history. Some compatibility cache flags have no backing cache yet. |
auth import-cookies | Import supported Chromium-family browser cookies for configured web-provider access. |
test https | Check the HTTPS path used by provider probes. |
doctor | Source build: diagnose configuration, plugins, and daemon health with actionable results. |
A LOCAL HOME FOR THE NUMBERS.
From a quick check
to the bigger picture.
The daemon keeps enabled providers refreshed and makes their usage available in a local browser dashboard. Run it in a terminal on Windows, macOS, or Linux, or use a systemd user service on Linux.
Provider dashboard
Inspect cached provider snapshots in your browser. The daemon and dashboard live on your machine, with the default dashboard at 127.0.0.1:6736/dashboard.
Background refresh
Choose enabled providers and polling frequency. Start, stop, and inspect the service from the CLI; the CLI also works without the daemon.
A separate dev profile
The dev installer uses usagestat-dev, a separate service, and separate configuration/data directories so you can try source features alongside a release.
Source build
History with useful context.
Explore saved daily usage with provider filters, preset or custom date ranges, and daily, weekly, or monthly groupings. Compare with the previous period and export the selected daily rows to CSV.
- 7, 30, 90, or 365 days, all saved history, or a custom range.
- Token and cost totals from providers with daily reports.
- UTC calendar dates and explicit recording coverage.
- Missing days stay gaps; quota-only providers keep snapshot charts.
Usage over timeILLUSTRATION
EARLIERDAILY USAGETODAY
Provider filters · date ranges · period comparisons · CSV export
usagestatdLeave the daemon running, then open the dashboard with usagestat dashboard in another terminal. Use usagestat dashboard --url to print the address over SSH. See setup for your system.
THE SAME DATA, WHEREVER YOU NEED IT.
A local HTTP API.
An open invitation.
Read provider metadata and cached snapshots from your own tools. The source build also adds normalized limit exports with machine-readable usage, remaining capacity, and reset information.
curl http://127.0.0.1:6736/v1/providers
curl http://127.0.0.1:6736/v1/usage
curl http://127.0.0.1:6736/v1/usage/claude| Method & endpoint | Purpose | Availability |
|---|---|---|
GET /health | Daemon health and availability. | Released |
GET /v1/providers | Discovered provider metadata. | Released |
GET /v1/usage | Cached usage snapshots for enabled providers. | Released |
GET /v1/usage/:providerId | A single provider’s cached usage. | Released |
POST /v1/refresh | Request a refresh of enabled providers. | Released |
GET /v1/limits | Cached, machine-readable limits for consumers. | Source build |
GET /v1/limits/:providerId | Machine-readable limits for one provider. | Source build |
GET /v0/management/quota-scheduler/status | Opt-in T3-compatible quotas; management key required. | Released |
The daemon binds to loopback by default. T3 compatibility is opt-in and uses its own management key. Configure service binding deliberately if using the backend beyond your own machine.
ONE BACKEND. MORE PLACES TO SEE IT.
Meet your workflow
where it already is.
UsageStat Bar
The desktop companion keeps usage close at hand on Windows, macOS, and Linux. Menu bars, native widgets, tray icons, Waybar, and Polybar read the CLI through their integrations, with shared provider settings.
Explore the barYour scripts & tools
Build a status line, desktop widget, or report using CLI output or the native API. Use the common snapshot format across providers.
T3 Code usage limits
Enable the CLIProxyAPI bridge and add the local hub in T3 Code. The current T3 integration displays supported Claude and Codex quota windows.
usagestat daemon t3 auto
usagestat daemon enable
usagestat daemon keyAdd http://127.0.0.1:6736 in T3 Code and use the printed key. The bridge reports quotas; it does not proxy inference or expose credential files.
BRING YOUR OWN PROVIDER.
A plugin system
with room to grow.
Provider integrations are JavaScript plugins hosted by a Rust backend. Start with the included template and return the same metric types used throughout the toolkit.
Shared metric types
Return progress meters, text rows, badges, and bar charts. Declare labels, scope, order, icons, and provider links in the manifest.
Several source modes
Build integrations for API keys, OAuth, local files, CLI tools, or browser sessions, with provider-specific source selection.
Useful host capabilities
Use the host’s HTTP client, local file access, logging, allowlisted environment variables, and allowlisted commands from a plugin context.
Flexible discovery
Use installed plugin directories, user configuration, environment overrides, or extra directories supplied on the command line.
A working starting point
Copy templates/provider-plugin, implement probe(ctx), and validate your plugin. Dev example providers live separately from the production bundle.
Custom command sources
Connect an existing script that prints UsageStat-style JSON as a configured provider source, without building a whole desktop integration.
CONFIGURATION YOU CAN READ.
Keep the controls
close to the data.
Plain configuration
Choose providers, refresh frequency, plugin directories, source modes, instance IDs, and display names in TOML. Use --config for a separate configuration and respect XDG paths.
Local storage
Configuration lives under ~/.config/usagestat; snapshots and history live under the corresponding local data directory. Provider probes still contact their configured provider endpoints.
Authentication helpers
Use provider-supported credentials, existing local sessions, or API keys. Cookie-import helpers support selected Chromium-family browser sessions; credential handling depends on the source.
Diagnostics you can act on
Validate plugins and configuration, inspect daemon status, and smoke-test HTTPS. The source-build doctor command adds a combined health report with JSON output.
Account routing: configured source instances can carry separate names and credentials. Compatibility flags such as --account, --account-index, and --all-accounts are accepted but do not currently route separate logins. Strict CLI --source routing is also plugin-dependent.
WINDOWS, MACOS & LINUX.
Pick the package
that fits your machine.
Get UsageStat for Windows, macOS, or Linux. Packages include the CLI, daemon, and provider plugins. Choose your system on the installation page for setup instructions.
| Channel | System | CPU |
|---|---|---|
| Windows downloads | Windows | See release downloads |
| macOS downloads | macOS | See release downloads |
| AUR | Arch Linux | x86-64 |
| Homebrew | Linux · system glibc 2.39+ | x86-64, ARM64 |
| COPR | Fedora 43, 44, 45, Rawhide | x86-64 |
| PPA | Ubuntu 24.04 LTS | amd64 |
| Release archives | Linux · glibc 2.39+ | x86-64, ARM64 |
Linux package availability varies by distro and architecture. UsageStat Bar is optional; choose the integration for your desktop platform.
Start with one command.
A little visibility today. A foundation for whatever you build next.
Feature reference: UsageStat README, CLI documentation, and T3 Code integration.