C ⠉ — a pixel C beside the braille cell ⠉ (dots 1 and 4, the two top dots: a meter at full).
Local-first, FOCUS-native cost and limit visibility for your AI coding tools.
Costroid shows you — right in your terminal — what your AI coding tools actually cost. It tracks both the subscription limits you're burning through (Claude Code, Codex, and Cursor session 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.
Early development — Phase 1. Costroid's first release, v0.1.0, is published. Install it via the packaged installers below (shell, PowerShell, Homebrew, npm), cargo install costroid, or cargo binstall costroid — or build from source (see Quickstart). The Phase-1 interface is in place; commands and flags may still evolve. Nothing in the Roadmap section (Phases 2–4) exists yet.
Phase 1 (v1) scope:
- Two views in one tool.
now— live 5-hour and weekly subscription limits with reset countdowns, plus your current API spend by model.trends— spend over day / week / month / year, grouped or filtered by model or app.
- Local logs only. Reads what Claude Code, Codex, and Cursor already write to disk. No API keys, no login, nothing leaves your machine.
- FOCUS-conformant export (JSON / CSV) so your cost data is standard and portable.
- Statusline mode for your shell, tmux, or Starship.
--liveauto-refreshing view and a--plainASCII mode for accessibility and pipes.- Braille rendering. Charts, meters, and bars are drawn in braille dots — dense, distinctive, and terminal-native.
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.
Not yet built — here's where Costroid is headed:
- Phase 2 — live quotas via your existing tool sessions, plus optional OAuth login (tokens stored only in your OS keychain, used strictly between your device and the provider). Threshold alerts.
- Phase 3 — a cross-platform tray / menu-bar app for Windows, macOS, GNOME, and KDE.
- Phase 4 — an MCP server (query your costs from inside your AI agent) and quality-per-dollar model recommendations.
- A separate, team-oriented web platform for company-wide cost management is planned as its own project.
See HANDOFF.md for the full plan and phase-by-phase acceptance criteria.
git clone https://github.com/Costroid/costroid
cd costroid
cargo install --path apps/cliv0.1.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 | shWindows (PowerShell):
powershell -ExecutionPolicy Bypass -c "irm https://github.com/Costroid/costroid/releases/latest/download/costroid-installer.ps1 | iex"Homebrew:
brew install Costroid/tap/costroidnpm:
npx costroidPrebuilt binary via cargo-binstall (downloads the attested release binary from GitHub, no compile):
cargo binstall costroidFrom crates.io (compiles from source):
cargo install costroidcostroid # 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 export --format json # FOCUS export (--format json | csv)
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 and export are always one-shot.
- No telemetry, by default. Any update check is opt-in and clearly disclosed.
- Your data stays on your machine. Phase 1 reads local logs only; nothing is uploaded.
- Secrets live in your OS keychain. When optional login arrives (Phase 2), tokens are stored via the system keychain and used only between your device and the provider — never routed through any Costroid server.
- 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.
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.
- Plan and architecture: HANDOFF.md
- Building Costroid, and the rules that AI coding agents must follow: AGENTS.md
- Contributions are welcome — please read AGENTS.md first.
Licensed under the Apache License, Version 2.0. See LICENSE.