Costroid
Local-first, FOCUS-native cost and limit visibility for your AI coding tools — right in your terminal.
The problem
AI coding tools spread your spend across three places that no single tool ties together: a subscription with opaque 5-hour and weekly caps (Claude Code, Codex) that you only notice when you hit them; a metered API bill in real dollars by model; and — increasingly — your own hardware, where running an open-weights model locally has a real but invisible energy-plus-amortization cost. Costroid puts all three in one place, by default entirely from the local logs those tools already write, with nothing leaving the machine, and normalizes everything into the open FOCUS standard so it is portable and vendor-neutral. Subscription limits and API costs are modeled separately, because they are different things: a subscription has a quota % and a reset timer; an API key has summable per-model dollars; and local inference has a measured/estimated cost-per-token with a break-even against the cloud.
🎬 Demo GIF — capture pending M3b (no committed asset yet).
Hero GIF: capture pending M3b. The 60–90s screen recording of a real run is captured on real hardware after the M3b wall-meter measurement run; there is no committed image yet, so this text placeholder stands in. To see the tool now, run
make demo(the Quickstart below) — all three FOCUS lanes in one ledger, fully offline. Every local-inference figure Costroid shows today is estimated — pending M3b measurement (see methodology).
Feature-complete at v0.6.0. Edition 2021, Apache-2.0. MSRV 1.88 (libraries + CLI), 1.92 (the taskbar).
Install
CLI (costroid):
# macOS / Linux (shell)
|
# Windows (PowerShell)
Taskbar (costroid-bar): downloadable binary archives, or cargo install costroid-bar. (No npm/Homebrew this cut.)
Build from source: git clone https://github.com/Costroid/costroid && cd costroid && cargo install --path apps/cli.
Quickstart / Demo
See the whole product end-to-end — all three FOCUS lanes in one ledger — over bundled synthetic sample data, fully offline, with no hardware and no cloud account:
make demo chains export (synthetic dev-tool logs → developer_tool) + import (synthetic AWS Bedrock FOCUS v1.2 → cloud_api) + bench (estimated Gemma 4, no hardware → local_inference) + breakeven (local-vs-cloud, a range), then merges them into a deterministic three-lane FOCUS 1.3 ledger at target/demo/demo-ledger.csv. It points discovery only at samples/local-logs (so it can never read your real logs) and pins the clock via SOURCE_DATE_EPOCH, so the artifact is byte-identical across re-runs (make demo-verify proves it; make help lists every target). Every figure is synthetic and estimated — "estimated — pending M3b measurement". (A hero-GIF screen recording is capture-pending M3b.)
Windows (no make) — the same ordered commands as raw cargo run (PowerShell 7+ recommended — it writes UTF-8 without a BOM, so the merged CSV header stays byte-identical; the binary needs --features power for bench/breakeven):
mkdir target\demo\nohome 2>$null
# Hermetic discovery: point ONLY at the samples and neutralize every other source, so the demo
# can never read your real ~/.claude / ~/.codex (mirrors the Makefile's DEMO_ENV).
$env:HOME="$PWD\target\demo\nohome"; $env:USERPROFILE=""; $env:CURSOR_DATA_DIR=""; $env:XDG_STATE_HOME=""; $env:ANTHROPIC_API_KEY=""
$env:CLAUDE_CONFIG_DIR="samples\local-logs\claude"; $env:CODEX_HOME="samples\local-logs\codex"
# (a) developer_tool — export the synthetic dev-tool logs
cargo run -q -p costroid --features power -- export --format csv | Out-File -Encoding utf8 target\demo\dev.csv
# (b) cloud_api — import the synthetic AWS Bedrock FOCUS v1.2 export
cargo run -q -p costroid --features power -- import --format focus-csv --version 1.2 --out csv samples\cloud-focus\aws-focus-v12.csv | Out-File -Encoding utf8 target\demo\cloud.csv
# (c) local_inference — deterministic estimated Gemma 4 bench (SOURCE_DATE_EPOCH pins the clock)
$env:SOURCE_DATE_EPOCH="1781913600"
cargo run -q -p costroid --features power -- bench --model gemma-4-31b-dense --tokens-in 2000 --tokens-out 18000 --out csv | Out-File -Encoding utf8 target\demo\local-31b.csv
cargo run -q -p costroid --features power -- bench --model gemma-4-26b-a4b --tokens-in 2000 --tokens-out 18000 --out csv | Out-File -Encoding utf8 target\demo\local-26b.csv
# break-even — local-vs-cloud crossover (a range, never a hero number)
cargo run -q -p costroid --features power -- breakeven --model gemma-4-31b-dense --compare-to claude-opus-4-8 --tokens-in 2000 --tokens-out 18000 --tokens-per-day 5000000 --plain
# merge the three lanes (identical FOCUS 1.3 headers) into one ledger (header + each lane header-skipped)
Get-Content target\demo\dev.csv | Set-Content -Encoding utf8 target\demo\demo-ledger.csv
foreach ($f in "target\demo\cloud.csv","target\demo\local-31b.csv","target\demo\local-26b.csv") {
Get-Content $f | Select-Object -Skip 1 | Add-Content -Encoding utf8 target\demo\demo-ledger.csv
}
Commands
| Command | What it does |
|---|---|
costroid (the default view) |
Live Claude + Codex 5h/weekly limits with reset countdowns, plus current API spend by model |
costroid trends |
Spend over time — --period day|week|month|year, --group model|app|total |
costroid frontier |
Cost-vs-quality frontier and where your spend sits; advisory, sourced, API-cost rows only |
costroid statusline |
Compact one-line status for shell / tmux / Starship (--wrap '<cmd>' escape hatch) |
costroid setup-statusline |
Wire Claude Code's statusLine to capture live 5h/7d quota (--undo to restore) |
costroid export --format json|csv |
FOCUS 1.3-conformant export |
costroid import <file> |
Import a foreign FOCUS v1.2 export (incl. AWS Data Exports / Bedrock; multi-currency) → Costroid FOCUS 1.3 cloud lane (--format focus-csv|focus-json, --version auto|1.2, --out json|csv, --pricing-override <file> to layer a user price file over the bundled catalog); pure local parse, no network |
costroid alerts / --check |
Opt-in threshold alerts (default off); --check is cron-friendly (exit 0/1/2) |
costroid --live |
Auto-refreshing interactive view |
costroid --plain |
One-shot ASCII, no color — screen-reader & pipe friendly |
Opt-in connections (behind --features connect, off by default): costroid connect / disconnect / connections [--check] link your own Anthropic/OpenAI usage-API key (stdin-only entry, instant revoke), and costroid reconcile puts your local estimate side by side with the vendor's billed invoice.
Local-inference economics (behind --features power, off by default — pure local compute, no network): costroid bench estimates a local model's cost-per-token (or --measures it with a wall meter), and costroid breakeven computes the local-vs-cloud crossover — "local breaks even at N tokens/day, or never (or infeasible), with the reason" — as a range + methodology + assumption stamp, never a single hero number. The hardware is amortized as a calendar-fixed capex; the marginal local rate is energy-only; the cloud side is the bundled per-token pricing catalog, with the dated DeepSWE-Bench $/task shown as a labeled reference (never the crossover math).
$ costroid breakeven --compare-to claude-opus-4-8 --tokens-per-day 5000000 --plain
Local breaks even at 87214 tokens/day.
At your 5000000 tokens/day: local is already cheaper
Sensitivity range: 69771 … 107804 tokens/day
Surfaces
- TUI — 9 numbered tabs (
1now,2trends,3providers,4models,5history,6budget,7forecast,8anomalies,9activity) plus ana/escfrontier overlay. Charts/meters/bars draw in braille dots, painted in Costroid's palette;--plain/NO_COLORstrip all color with byte-identical output. Built with--features power, aboverlay adds the local-vs-cloud break-even + a comparison facet (estimate; no network). - Taskbar (
costroid-bar) — always-on tray glance (your most-constrained quota meter, in the dot-density warning language) plus a live cockpit (Overview, opt-in alert banner, Budget / Forecast / Anomalies / Providers). egui/eframe + tray-icon, AccessKit on, a pure consumer of the same local data. macOS/Windows tray paths compile but are not yet field-verified. - Local web app (
costroid-server) — a loopback-only (127.0.0.1) HTTP server over your stored ledger with three views: timeline (spend over time, by tool/model), comparison (actual local vs counterfactual cloud list price for the same workload), and break-even (the local-vs-cloud crossover). Server-rendered HTML (tables + inline SVG, no JS) + a?plaintext fallback + a JSON API (/api/...); all assets are embedded in the binary, with zero external requests — it works fully offline. A separate binary, never linked into thecostroidCLI (which stays byte-for-byte no-network) and never linked to the local-inference engine; its guarantee is loopback-bind, no outbound egress (proven by a static allowlist + a runtime strace check).
Providers
Claude Code and Codex (full cost + quota); Cursor (detect-only — cost/quota "unavailable"). Cursor live quota, GitHub Copilot, Antigravity, and Gemini own-key are discovery-gated and never built speculatively.
What this does that ccusage doesn't
ccusage is the great single-tool token-cost reader; Costroid is a broader, standards-native cost lens. These are feature contrasts, not a ranking:
| Capability | ccusage | Costroid |
|---|---|---|
| Claude Code / Codex token cost from local logs | yes | yes |
| FOCUS-native output (the open FinOps standard, portable/vendor-neutral) | no | FOCUS 1.3 in/out (v1.2 import → v1.3 export) |
| Three-lane ledger — developer-tool + cloud-API + local-inference, in one ledger (never summed across) | dev-tool only | all three lanes |
| Cloud/API cost lane — import an AWS Data Exports / Bedrock FOCUS bill, multi-currency | no | yes (costroid import) |
| Local-inference economics — measured/estimated cost-per-token for a model on your own hardware | no | yes (costroid bench, the power feature) |
| Break-even — local-vs-cloud crossover ("breaks even at N tokens/day, or never, with the reason") | no | yes (costroid breakeven) |
Loopback web UI — a local-only (127.0.0.1) three-view app, zero external requests |
no | yes (costroid-server) |
| Estimate-vs-invoice reconciliation against the provider's billed amount | no | yes (costroid reconcile) |
| Zero-network default, enforced (strace offline-acceptance + forbidden-crates gate) | n/a | yes (byte-for-byte no-network CLI) |
Architecture at a glance
A Rust Cargo workspace — 10 members (3 apps + 7 crates) — feeding one three-lane FOCUS ledger; the loopback web server is a separate binary that never links the CLI or the local-inference engine. (Full canon: docs/ARCHITECTURE.md.)
flowchart TD
subgraph apps["apps"]
cli["costroid (apps/cli)<br/>CLI + TUI + statusline"]
bar["costroid-bar (apps/bar)<br/>egui/eframe taskbar"]
server["costroid-server (apps/server)<br/>loopback-only HTTP + web UI"]
end
subgraph crates["crates"]
core["costroid-core<br/>engine: cost calc, FOCUS, bench, breakeven, reconcile"]
providers["costroid-providers<br/>Claude/Codex/Cursor adapters + FOCUS import"]
focus["costroid-focus<br/>FOCUS 1.3 types"]
config["costroid-config<br/>budget/alerts TOML"]
connect["costroid-connect<br/>ALL network + secrets (feature-gated, OFF)"]
power["costroid-power<br/>local-inference engine (leaf, power feature)"]
store["costroid-store<br/>SQLite ledger (store feature)"]
end
cli --> core
cli --> config
bar --> core
bar --> config
cli -. "feature: connect" .-> connect
bar -. "feature: connect" .-> connect
connect --> core
core --> providers
core --> focus
config --> core
server --> core
server --> store
store --> focus
cli -. "feature: power (CLI orchestrates; no core->power edge)" .-> power
cli -. "feature: store" .-> store
subgraph lanes["one FOCUS ledger — three lanes, never summed across"]
dev["developer_tool<br/>(Claude/Codex logs)"]
cloud["cloud_api<br/>(imported FOCUS bills)"]
local["local_inference<br/>(costroid bench)"]
end
providers --> dev
providers --> cloud
power --> local
Guarantees
- Local-first, zero-network default. The default build reads local logs only and makes no network calls (enforced by a strace offline-acceptance test + a two-tier forbidden-crates test). Network happens only under
--features connect, on an explicitconnect/connections --check/reconcileaction, as an HTTPS GET to the one provider host you authorized. - No telemetry, ever. Any update check is opt-in and off by default.
- Secrets live only in your OS keychain (
keyring) — read from stdin, never written to disk, config, or logs, never routed through any server. A usage-API key is organization-wide;connectwarns at paste time and recommends a dedicated, instantly-revocable key. TLS validates against your OS trust store (no cert pinning) — see SECURITY.md. - Cost is always an estimate (your tokens × current prices), built to reconcile against the provider invoice, which is the source of truth.
--plaineverywhere, never color alone (the dot-density grid is the cue); permissive licenses only.
More
- Standards: emits FOCUS 1.3-conformant records — portable and vendor-neutral.
- Roadmap: docs/ROADMAP.md. Release history: CHANGELOG.md. Architecture: docs/ARCHITECTURE.md. Build rules for AI coding agents: CLAUDE.md.
License
Apache-2.0. See LICENSE. Costroid uses only local and provider-sanctioned data sources and never reuses a credential or session against an undocumented or internal endpoint; if you connect your own key, you remain responsible for complying with each provider's terms of service.