costroid 0.6.0

Local-first, FOCUS-native cost and limit visibility for your AI coding tools, right in your terminal.
costroid-0.6.0 is not a library.

Costroid

Local-first, FOCUS-native cost and limit visibility for your AI coding tools — right in your terminal.

status license

Costroid shows you — right in your terminal — what your AI coding tools actually cost. It tracks both the subscription limits you're burning through (your Claude Code and Codex 5-hour and weekly caps, with reset countdowns) and the real dollars on your API bill, broken down by model. Everything runs locally: it reads the logs those tools already write to your machine, sends nothing anywhere, and normalizes the data into the open FOCUS standard so your cost data is portable, auditable, and ready for whatever you plug it into next.

It's the kind of tool that should be free and open, so it is.

Status

Early development. Costroid's v0.6.0 release ships the costroid-bar taskbar — the last surface: an always-on tray glance (your most-constrained quota meter, in the dot-density warning language) plus a small live cockpit window with the Overview, the opt-in alert banner, and Budget, Forecast, Anomalies, and Providers panels — painted in the same braille/dot language as the terminal UI, with screen-reader accessibility (AccessKit) on. It builds on the analytical TUI tabs + opt-in alerts (Providers, Models, History, Budget, Forecast, Anomalies + threshold alerts that fire at 80% / 95% of a quota or over a budget target, off by default, v0.5.0), the opt-in connections line (your own Anthropic/OpenAI usage-API key + costroid reconcile, off by default, v0.4.0), live Claude subscription quota (5-hour + weekly via Claude Code's statusLine, v0.3.0), and the local cost lane (now, trends, statusline, export, the cost-vs-quality frontier view, Cursor detect-and-defer, WSL Windows-root auto-detection, v0.2.0). The default build still reads only local logs and makes zero network calls. Install the CLI via the packaged installers below (shell, PowerShell, Homebrew, npm), cargo install costroid, or cargo binstall costroid; the taskbar ships as downloadable binary archives + cargo install costroid-bar — or build from source (see Quickstart). Commands and flags may still evolve.

What Costroid does

Shipping today (v0.6.0):

  • Two views in one tool.
    • now — your Codex and live Claude 5-hour and weekly limits with reset countdowns (Claude via its statusLine), plus your current API spend by model.
    • trends — spend over day / week / month / year, grouped or filtered by model or app.
  • Six analytical tabs (number 1–8 or Tab / Shift-Tab) — Providers (each tool's data source, auth, and what's available vs unavailable), Models (per-model API spend + token mix fused with the frontier), History (the full per-turn FOCUS record, newest-first, scrollable), Budget (your monthly $ targets vs actual API-lane spend, with a pace cue), Forecast (run-rate month-end projection + per-quota burn ETAs, hedged), and Anomalies (spend-spike + model-mix-shift callouts vs your own recent history).
  • Opt-in threshold alerts (alerts / alerts --check) — an inline banner + a cron-friendly exit-code check when a quota window crosses 80% / 95% or a budget goes over target, plus two optional advisory heads-ups (a month-end projection over your total budget, a daily spend spike vs your own norm); off by default, no daemon, no network.
  • Cost-vs-quality frontier (frontier) — the published cost-vs-quality frontier (DeepSWE + CursorBench) and where your own spend sits on it; advisory, sourced, API-cost rows only.
  • Local logs only. Reads what Claude Code, Codex, and Cursor already write to disk. Today's release needs no API keys and no login, and nothing leaves your machine. (Optional, opt-in connections — your own API key — shipped in v0.4.0, with a sanctioned OAuth login still planned; the local-only path always stays the default.)
  • FOCUS-conformant export (JSON / CSV) so your cost data is standard and portable.
  • Statusline mode for your shell, tmux, or Starship.
  • --live auto-refreshing view and a --plain ASCII mode for accessibility and pipes.
  • Braille rendering. Charts, meters, and bars are drawn in braille dots — dense, distinctive, and terminal-native.
  • Taskbar / menu-bar app (costroid-bar, new in v0.6.0) — an always-on tray glance (your most-constrained limit, in the dot-density warning language) plus a live cockpit window (Overview + opt-in alert banner + Budget / Forecast / Anomalies / Providers), painted in the same dot/braille language and screen-reader-accessible (AccessKit). A pure consumer of the same local data — no new network, no telemetry. Ships as binary archives + cargo install costroid-bar. (Deep analysis — trends, models, history, frontier — stays in the costroid terminal app.)

A note on the two views: subscription limits and API costs are deliberately separate, because they're different things. A subscription is a flat monthly fee, so it has a quota percentage and a reset timer but no per-use dollar amount. An API key is pay-as-you-go, so it has real, summable dollars per model. Costroid shows both, and a model you use both ways appears in each view, marked by access path.

Roadmap

Where Costroid is headed:

  • Live Claude quota — shipped in v0.3.0. Claude Code's statusLine hook hands Costroid your real 5-hour and weekly limits locally — no login, no token reuse. costroid setup-statusline wires it up and captures the data, and the now-screen and statusline render those limits (with a color-free ? unverified cue and a labeled estimate fallback when a reading can't be trusted, never a confident wrong number).
  • Cost-vs-quality frontier (costroid frontier) — shipped in v0.2.0. Plots the published cost-vs-quality frontier and where your own spend sits on it; advisory and sourced, never "just use the cheapest."
  • Connections (your own key, opt-in) — shipped in v0.4.0. Optional, default-off, feature-gated connections fetch live numbers no local log carries — your own Anthropic or OpenAI usage-API key, and a sanctioned OAuth login where the provider offers one. Costroid never reuses a session or token against an undocumented endpoint, so a provider with no sanctioned source — Cursor today, and Gemini, which exposes no static-key usage API — stays detect-only and shows "unavailable" until an official API exists. Tokens live only in your OS keychain and are used strictly between your device and the provider; connect warns at paste time that an admin key is organization-wide and recommends a dedicated, instantly-revocable one. v0.4.0 ships it all — the feature-gated costroid-connect crate, its OS-keychain credential store, the generic authorized-host HTTPS client, the Anthropic + OpenAI usage-API adapters, the estimate-vs-invoice reconciliation engine, the costroid connect/disconnect/connections CLI (stdin-only key entry, instant revoke), and the costroid reconcile view that puts your local estimate side by side with the vendor's billed invoice (signed variance per day and model, honest about every gap, never presenting the estimate as the bill) — all off by default, with the default build still making zero network calls.
  • Analytical tabs + alerts — shipped in v0.5.0. The Providers, Models, History, Budget, Forecast, and Anomalies TUI tabs land alongside opt-in threshold alerts (costroid alerts / --check + an inline banner): a quota window crossing 80% / 95% or a budget going over its monthly $ target, default off, pure-local, no daemon.
  • Taskbar / menu-bar app — shipped in v0.6.0. The costroid-bar surface, built in egui (no webview): an always-on tray glance + a live cockpit window (Overview, opt-in alert banner, Budget / Forecast / Anomalies / Providers), screen-reader-accessible (AccessKit), painted in the same dot/braille language as the terminal UI — the last surface, and a pure consumer of what the core already computes. (The macOS/Windows tray paths are built but not yet field-verified, so the GUI ships as binary archives + cargo install costroid-bar; the one-click npm/Homebrew installers stay CLI-only until that matrix is confirmed.)
  • Maybe later — an MCP server (query your costs from inside your AI agent) remains a speculative, uncommitted future surface.
  • A separate, team-oriented web platform for company-wide cost management is planned as its own project.

See CLAUDE.md for the build scope and the rules that AI coding agents follow. (Costroid's detailed design specs — architecture, data model, product plan — live in docs/.)

Quickstart

Build from source (works today)

git clone https://github.com/Costroid/costroid
cd costroid
cargo install --path apps/cli

Packaged installers

v0.6.0 is published — all commands below work today. Built and released by cargo-dist (binary dist). Release binaries carry build-provenance attestations + checksums but are not yet OS-code-signed, so on first run macOS may show an "unidentified developer" prompt and Windows a SmartScreen prompt — see Security & privacy.

macOS / Linux (shell):

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/Costroid/costroid/releases/latest/download/costroid-installer.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -c "irm https://github.com/Costroid/costroid/releases/latest/download/costroid-installer.ps1 | iex"

Homebrew:

brew install Costroid/tap/costroid

npm:

npx costroid

Prebuilt binary via cargo-binstall (downloads the attested release binary from GitHub, no compile):

cargo binstall costroid

From crates.io (compiles from source):

cargo install costroid

Usage

costroid                         # interactive "now": live limits + current API costs
costroid trends                  # interactive spend-over-time view
costroid trends --period week    # day | week | month | year
costroid trends --group model    # model | app | total
costroid --live                  # auto-refresh the interactive view
costroid statusline              # compact one-line status for shell / tmux / Starship
costroid setup-statusline        # wire Claude Code's statusLine to capture live 5h/7d quota
costroid setup-statusline --undo # restore the original statusLine + remove the cache
costroid export --format json    # FOCUS export (--format json | csv)
costroid alerts                  # opt-in threshold alerts (default off; enable in config)
costroid alerts --check          # cron-friendly: exit 0 = clear, 1 = a crossing, 2 = error
costroid --plain                 # one-shot ASCII, no color (screen-reader & pipe friendly)

On an interactive terminal, costroid and costroid trends open a navigable view (press ? for keys, q to quit); when the output is piped or --plain is set, they render once and exit. statusline, export, and alerts are always one-shot.

costroid alerts is off by default. Enable it in ~/.config/costroid/config.toml with an [alerts] section (enabled = true, plus optional quota_warn / quota_critical fraction overrides). Once on, it warns you when a quota window crosses 80% / 95% (only off a fresh, cross-checked reading — never a guess) or when your monthly $ budget goes over target, as an inline banner atop the now view and via the costroid alerts list. costroid alerts --check is built for cron — it stays quiet when clear and exits non-zero on a crossing, so you can wire it into a notification of your own. It is pure-local: no daemon, no network, no telemetry. (The two budget targets it reads live in the same [budget] config the Budget tab uses.)

Two optional advisory heads-ups can be turned on alongside those hard crossings, each its own opt-in sub-flag (still requiring enabled = true): forecast = true fires when your month-end projection would exceed your total budget (only off a settled projection — never the noisy first days of the month, and never when you're already over, which the budget alert already covers), and anomalies = true fires on a daily spend spike versus your own recent norm. Both are advisory by nature — a softer heads-up that sorts after the quota/budget crossings — and both are off by default.

costroid setup-statusline is idempotent and safe: it backs up settings.json first (restore with --undo), injects a capture snippet into an existing statusLine or sets Costroid as the status line if you have none, and writes only two percentages + two reset stamps to a local cache — never a token, prompt, or credential, and never over the network. (The captured quota is read, sanitized, cross-checked, and rendered on the now-screen and statusline.) If you have a statusLine you can't edit through setup-statusline, wrap it manually: costroid statusline --wrap '<your-status-command>' captures the quota and then runs your command on the same input (it degrades to a blank line on error, never breaking your prompt). (costroid statusline --capture-only is the internal capture step the generated snippet calls, not a command you run directly.)

Security & privacy

  • No telemetry, by default. Any update check is opt-in and clearly disclosed.
  • Your data stays on your machine. The default, local-only build reads local logs only and makes no network calls — enforced by an offline-acceptance test. Network access happens only through the opt-in, feature-gated connections path, and only to a provider endpoint you explicitly authorized; nothing is uploaded to Costroid.
  • Secrets live in your OS keychain. The keychain credential store and the costroid connect CLI live in the feature-gated costroid-connect path, off by default — the default binary doesn't even link it, and only an explicit connect / connections --check / reconcile reaches the network. When you do connect, your key is read from stdin only (never an argument or environment variable), goes only to the OS keychain — never to disk, a config file, or a log — and is used only between your device and the provider, never routed through any Costroid server.
  • When you connect, treat the key as a root credential. A provider "usage API" key is organization-wide — it can read your whole organization's usage and billing — so costroid connect warns you at paste time and recommends creating a dedicated, instantly-revocable key (revoke it in the provider console if the machine is ever compromised). Connections validate TLS against your OS trust store and Costroid does not pin certificates, so connect only on a host whose trust store you control. See SECURITY.md for the full transport-trust model.
  • Attested releases. Release binaries carry keyless GitHub build-provenance attestations and SHA-256 checksums — verify with gh attestation verify <file> --repo Costroid/costroid. OS code-signing (macOS notarization, Windows Authenticode) is not yet in place, so first run may show an unidentified-developer / SmartScreen prompt.
  • Local cost figures are estimates (your tokens × current prices). Costroid is built to reconcile them against your actual provider invoices, which are the source of truth.

Standards

Costroid follows FinOps Foundation practice and emits FOCUS 1.3-conformant records — the open specification that now covers AI billing data — so your cost data is portable and vendor-neutral from the start.

Project status & contributing

  • Detailed design specs (architecture, data model, product plan): docs/
  • Building Costroid, and the rules that AI coding agents must follow: CLAUDE.md
  • Contributions are welcome — please read CLAUDE.md first.

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Costroid uses only local and provider-sanctioned data sources — it never reuses a credential or session against a non-sanctioned, undocumented, or internal endpoint, and the default build makes no network calls. If you optionally connect your own API key or a sanctioned login, you remain responsible for your own use of those credentials and for complying with each provider's terms of service.