agentstat 0.1.1

Read-only AI provider usage, quota, balance, and reset data
Documentation

Fetch provider-reported data through one async API and use it in your own CLI, dashboard, or application. agentstat is a library: your application decides when to fetch, where to store results, and how to display them.

  • Quota windows, utilization, limits, and reset times when the provider reports them.
  • Exact decimal balances and spend, with currencies and credit units kept separate.
  • Typed errors and batch fetching with bounded concurrency.
  • Caller-supplied credentials, with explicit opt-in for local files and CLI probes.

Source version: 0.1.1. Implemented adapters have synthetic request and normalization fixtures. Help us validate providers with real accounts. HTTP adapters target Linux, macOS, and Windows. Local CLI probes support Unix. The table reflects the current source checkout; check the released crate's features when using crates.io.

Quick start

After version 0.1.1 is published, add the library to your Rust application:

cargo add agentstat@0.1.1 --features local-files
cargo add tokio --features macros,rt-multi-thread

Or put the same dependencies in Cargo.toml:

[dependencies]
agentstat = { version = "0.1.1", features = ["local-files"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Before publication, use a path to your checkout instead, for example agentstat = { path = "../agentstat", features = ["local-files"] }.

This src/main.rs reads your existing Codex CLI login and prints the reported quota windows. local-files is opt-in at both build time and runtime:

use agentstat::{Client, ProviderId, local::CredentialLocation};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder().allow_local_files(true).build()?;
    let request = client
        .load_local_credentials(ProviderId::Codex, CredentialLocation::Native)
        .await?;
    let snapshot = client.fetch(request).await?;

    for window in &snapshot.windows {
        println!("{} | model: {}",
            window.id,
            window.model.as_deref().unwrap_or("not specified"));
        if let Some(percent) = window.utilization_percent {
            println!("  Used: {percent:.1}%");
        }
        if let Some(reset) = window.resets_at {
            println!("  Resets: {reset}");
        }
    }
    Ok(())
}

Run it with cargo run. For a fuller model-window report, copy or adapt the model usage example. A model field identifies a provider-reported model or group; a missing field does not imply a separate per-model measurement. Five-hour and weekly windows are quota periods, not time spent coding. The provider may omit a limit, reset, or model breakdown.

Codex and Claude are enabled by default. Select other integrations by their feature ID in the table below, for example:

agentstat = { version = "0.1.1", default-features = false, features = ["cursor", "local-files"] }

all-providers enables every catalog feature, including planned integrations that still return an unsupported error. Enable only the providers you need.

How it works

flowchart LR
    A[Your Rust application] --> B[FetchRequest]
    C[Caller credentials or opt-in local login] --> B
    B --> D[Client validation and routing]
    D --> E[Provider adapter]
    E --> F[Read-only provider API or opt-in CLI probe]
    F --> G[Normalized UsageSnapshot]
    G --> A

Your application owns credentials, fetch timing, caching, and display. Client checks provider support and account scope, performs a fetch, and returns typed windows, balances, spend, and warnings. Reuse one Client for connection pooling. fetch_many keeps request order and returns one result per request, so one failed account does not hide another account's result.

Examples

Use case Example What it shows
Model and quota windows from a local CLI login model_usage.rs Read Codex, Claude, or Cursor credentials, then inspect model labels, utilization, limits, and resets
Live usage from your available accounts real_usage.rs Codex, Claude, Cursor, Antigravity, and OpenCode with their distinct credential paths
Caller-supplied token fetch.rs Supply a token and serialize the typed snapshot as JSON

These examples use the public crate API, so their Client and FetchRequest code can be moved into another Rust project. The first two examples run from this repository with cargo run --example ...; fetch.rs needs AGENTSTAT_TOKEN. For a model-window report from your existing Codex login, run:

cargo run --features local-files --example model_usage -- codex

Try your real account

From this repository, with the required credentials or CLI history available:

Account Live command Credentials used
Codex cargo run --features local-files --example real_usage -- codex Existing local OAuth login
Claude Code cargo run --features local-files --example real_usage -- claude Existing local OAuth credential file
Cursor / agent cargo run --features cursor,local-files --example real_usage -- cursor Existing CLI auth.json
Gemini app cargo run --features gemini --example fetch -- gemini Existing bearer token in AGENTSTAT_TOKEN
Antigravity / agy cargo run --features antigravity,local-probes --example real_usage -- agy Installed CLI login; Unix only
OpenCode CLI / Console cargo run --features opencode-local --example real_usage -- opencode-clicargo run --features opencode --example real_usage -- opencode CLI session history (Unix only)Console cookie in OPENCODE_COOKIE
OpenCode Go cargo run --features opencodego --example real_usage -- go Go API key supplied in OPENCODE_GO_API_KEY

The examples fetch live data and return an error if the fetch fails. They never substitute demonstration values. OpenCode Zen/Console needs a Console cookie; OpenCode Go uses its API key. OpenCode CLI/local reports recorded 30-day session tokens and cost, not account quota or balance. Older CLI versions without JSON statistics provide rounded totals. Some CLI logins use OS credential stores that agentstat does not read. See the usage guide for cookie setup, native file paths, account selection, direct token access, and platform restrictions.

Currently supported

The table highlights seven integrations available in the current source checkout. For the complete catalog, see provider coverage. Not every provider exposes hourly or weekly limits.

The test coverage status describes automated coverage. Extended tests means multiple dedicated provider scenarios beyond the shared request and normalization fixtures. Fixture tests means those shared fixtures cover the provider's request and normalized result. Real-account checks are welcome for every provider.

Provider Feature ID Test coverage Available data
Codex codex Extended tests Five-hour, weekly, and additional quotas; credits and resets
Claude claude Extended tests Subscription quotas, model windows, extra usage; Admin costs
Cursor cursor Extended tests CLI or dashboard usage, plan allowances, on-demand spend and resets
OpenCode Zen / Console / CLI opencode; optional opencode-local Extended tests Console Go quotas and Zen PAYG spend/balance; local CLI session tokens and cost
OpenCode Go opencodego Extended tests Key-authenticated five-hour, weekly, and monthly percentages and resets
Gemini app gemini Fixture tests Model quota buckets using an existing bearer token
Antigravity antigravity Extended tests Grouped five-hour/weekly quotas and resets; optional agy probe

For endpoint details, authentication restrictions, and omitted enrichments, see full provider coverage. The coverage manifest records the status of every catalog entry.

Coming soon

See the roadmap for planned integrations and entries outside the current scope.

Contributions wanted

We need people with access to different providers to check agentstat against their real usage pages. A successful check is useful too: it helps maintainers spot endpoint or response changes and improve confidence in the adapters above.

Help needed How to contribute
Real-account checks Run a live example, compare its results with the provider's usage page, then share the result.
Adapter fixes If a provider's response differs, add a redacted synthetic fixture and a focused fix. See contributing.
More providers Pick an entry from Coming soon and discuss its read-only usage endpoint before opening a pull request.

For a field report, include the provider, crate version or commit, enabled features, platform, credential type, date, and CLI version when relevant. Describe what matched or differed without sharing tokens, cookies, account IDs, or raw authenticated responses. The contribution guide has a short checklist.

Data and credentials

Quota windows describe allowance consumption, not hours actively spent coding. Missing values stay missing; limits distinguish Known, Unknown, and Unlimited. Monetary values use exact decimals serialized as strings. Quota allowances and billed spend are separate concepts.

Pass a bearer token, API key, or full Cookie header as the provider requires. The direct adapters do not log in, renew tokens, extract browser credentials, or write credential files. Local file reads and probes require both a Cargo feature and a runtime opt-in. An installed CLI owns its authentication and runtime behavior.

Fetches have a 30-second deadline and a 2 MiB HTTP response limit by default. There are no automatic retries, redirects, or background polling. Errors omit remote response bodies and credential values. Private provider APIs can change; check the returned data against your provider's usage page.

Documentation and community

Resource What you will find
Usage guide Credentials, scopes, live examples, and transport options
Wiki Installation, examples, troubleshooting, issues, and roadmap
Provider coverage Data surfaces and restrictions for every provider
Roadmap Planned integrations and entries outside the current scope
Development guide Architecture, feature checks, and packaging
Release guide Tag-triggered crates.io publishing and GitHub Releases
Contributing Bug reports, provider adapters, and pull requests
Code of conduct Community expectations and reporting concerns
Security policy Reporting vulnerabilities and credential exposure

Support development through GitHub Sponsors or Buy Me a Coffee.

Run the local checks:

cargo fmt --check
cargo test --all-features
cargo test --no-default-features
cargo clippy --all-features --all-targets -- -D warnings
python3 scripts/check_coverage.py

The regular tests use synthetic fixtures and in-memory HTTP, with no live accounts required. CI also runs socket smoke tests on Linux, macOS, and Windows.

License

MIT © 2026 agentstat contributors.