Know your AI spend at a glance — quota progress bars, API-equivalent costs, and usage history for Claude and Codex, right in the Windows tray.

Quick Start · Clients · Provider Data · Data Lifecycle · Dashboard · Models · Cost Tracking · Development · Security

QuotaBar sits in the Windows system tray, reads credentials and usage logs from known local CLI paths, and surfaces quota windows, cost analytics, usage history, and reset notifications without leaving your workflow.

QuotaBar does not scan your disk for credentials. It reads only known provider paths and redacts sensitive values before logging.

Direct downloads — these links always serve the latest version:

1. Download the installer (or the portable build) from the links above.
2. Run it — Windows may show a SmartScreen prompt since the app isn't signed; click More info → Run anyway.
3. QuotaBar starts automatically and appears in the system tray.

Updates are built in for the installer. Check for new versions in the System tab — the update downloads in the background and is applied on the next restart.

flowchart LR
  A[Claude CLI] --> D[QuotaBar]
  B[Codex CLI] --> D
  C[Local JSONL logs] --> D
  D --> E[Tray progress bars]
  D --> F[Dashboard and reports]
  D --> G[Notifications]
  H[LiteLLM pricing] -. online .-> D

For end users:

• Windows
• Claude CLI login, Codex CLI login, or both
• Local provider usage logs for historical cost and report data

Node.js is not required — the installer bundles its own runtime.

For development (building from source):

• Node.js and npm

Early MVP: Provider quota data depends on unofficial endpoints that may change without notice. QuotaBar handles failures defensively and keeps stale data visible when live refreshes fail.

npm install
npm run build
npm run dev          # Electron opens with a tray icon in the system tray

To create a Windows installer and portable artifacts:

npm run package      # Output written to package-output/

Build output (compiled JS) is written to dist/.

Sign in with the local CLI tools first:

claude login
codex login

QuotaBar reads credentials only from known provider paths:

Provider	Credential path
Claude	~/.claude/.credentials.json
Codex	${CODEX_HOME:-~/.codex}/auth.json

CLAUDE_CONFIG_DIR and CODEX_HOME may contain comma-separated roots. QuotaBar deduplicates existing roots and combines usage data from them.

QuotaBar is path-based, not client-based — it doesn't care which app produced the data, only that the data lands in the known provider directories (~/.claude, ~/.codex). Any client that writes its credentials and usage logs there is automatically supported.

Client	Live quota	History / cost	Notes
Claude CLI	✅	✅	Reference client. Writes to ~/.claude.
Claude Code VS Code extension	✅	✅	Same Claude Code engine — shares ~/.claude.
Claude Desktop app (Code tab)	✅	✅	Code sessions write transcripts to ~/.claude/projects.
Codex CLI	✅	✅	Reference client. Writes to ~/.codex.
Codex Windows app	✅	✅	Uses ~/.codex (auth.json + sessions/).
Codex IDE extension	✅	✅	Uses ~/.codex (auth.json + sessions/).

Two boundaries to keep in mind:

• Custom directories. If a client uses a non-default home, point QuotaBar at it via CLAUDE_CONFIG_DIR / CODEX_HOME (comma-separated roots are merged). QuotaBar does not scan the disk for other locations.
• Live quota vs. history are independent. History only needs usage logs (projects/**/*.jsonl, sessions/**/*.jsonl). Live quota bars additionally need a valid .credentials.json / auth.json at the known path — a client that stores tokens elsewhere will still show history, but no live bars.

The quick check for any client: confirm that .jsonl files appear under ~/.claude/projects/ or ~/.codex/sessions/.

Provider	Live quota source	Historical cost/report source
Claude	~/.claude/.credentials.json plus OAuth usage endpoint	~/.config/claude/projects/**/*.jsonl, ~/.claude/projects/**/*.jsonl
Codex	${CODEX_HOME:-~/.codex}/auth.json plus usage endpoint	${CODEX_HOME:-~/.codex}/sessions/**/*.jsonl

Claude and Codex quota windows are fetched through unofficial provider endpoints. Those integrations are isolated in provider/auth modules and are treated as best-effort data sources.

⚠️ Providers delete their usage logs over time. QuotaBar can only see logs a provider still keeps on disk. Claude removes session transcripts older than cleanupPeriodDays (default: 30 days) — raise it in ~/.claude/settings.json (e.g. { "cleanupPeriodDays": 1095 } for ~3 years) to keep more. Codex currently keeps all sessions, but the same rules apply if that ever changes. See Data Lifecycle for how QuotaBar makes history permanent despite this.

Providers (Claude, Codex) write raw usage logs locally and delete them after a while (Claude: 30 days by default). QuotaBar treats those files as ingestion-only sources: it incrementally converts new or changed records into the portable usage store under %USERPROFILE%\.quotabar-win\usage\. Dashboard, History, Models, Analytics, and Reports read the portable store, not the provider logs. An ingested event survives after the provider removes its original log.

flowchart TD
  start([QuotaBar starts / hourly tick]) --> scan[Scan provider logs<br/>Claude + Codex JSONL]
  scan --> diff{File new or changed<br/>since last run?}
  diff -->|no| keep[Keep stored events]
  diff -->|yes| ingest[Sanitize and ingest events]
  ingest --> store[(Portable usage store<br/>immutable events)]
  keep --> store
  store --> ui[Dashboard · History · Models · Reports]
  gc[/Provider garbage collection<br/>deletes logs older than retention/]
  gc -.->|raw log removed| scan
  store -. already-aggregated days stay .-> store

What this means in practice:

Takeaway: Run QuotaBar regularly so provider logs are ingested before they expire. Raising cleanupPeriodDays widens that safety margin.

Open System → QuotaBar and choose Export data to create a portable ZIP. The archive contains portable statistics, quota snapshots, machine-independent settings, notification state, and the manifest required to verify every entry. It never contains provider logs, auth.json, .credentials.json, application logs, caches, backups, or the source machine's ingestion paths.

System Import accepts only ZIPs created by Export data. Choose Import data, select a portable export ZIP, review the replacement warning, and confirm. Import is a replacement, not a merge: the archive's portable statistics and settings replace the corresponding local data. Before anything is replaced, QuotaBar creates and verifies a full timestamped backup in %USERPROFILE%\QuotaBar Backups\, then restarts to apply the staged import.

The automatic file is a private full same-machine safety backup used by recovery, not a portable import archive. It can contain application logs, caches, and target-local paths, so do not share it or import it into another Windows account. To restore one manually:

1. Fully quit QuotaBar, including its tray process.
2. Separately preserve the current %USERPROFILE%\.quotabar-win\ directory so the restore can be reversed.
3. Extract the trusted automatic backup ZIP into a temporary directory.
4. While QuotaBar remains stopped, replace the contents of %USERPROFILE%\.quotabar-win\ with the extracted backup contents.
5. Restart QuotaBar and verify the restored state.

Portable export archives are portable across Windows accounts. On import, saved Claude and Codex roots from the source account are removed; QuotaBar discovers only the target account's known provider paths. For example, importing a portable export created by Alice while signed in as Bob does not keep C:\Users\Alice as an active root.

The History tab shows per-period cost and token breakdowns served from the portable usage store.

Weekly buckets start on Monday.

The Models tab breaks down token and cost data by model across your full history. It includes KPI tiles, a model distribution chart, price/performance scatter, sortable model table, adoption timeline, and cache-efficiency summaries.

The Analytics tab shows longer-term patterns across the full history.

The ROI factor is API cost ÷ (subscription cost × window_days / 30) — normalised so any window length is directly comparable to a monthly subscription price.

QuotaBar fires Windows toast notifications for quota and cost events. Rules are configured individually with enable/disable toggles, cooldown durations, and global quiet hours.

All fired notifications are stored in the Notifications tab history with timestamps and full details.

QuotaBar reads local JSONL logs, fetches current model pricing from LiteLLM when online, and calculates API-equivalent costs in USD.

For historical API cost pricing, QuotaBar keeps compact local price epochs per model. Each event uses the latest locally observed epoch at or before its timestamp. Claude events with source costUSD, and values already stored in the portable usage store, remain authoritative. On older installations with no eligible local epoch, QuotaBar uses the current price for compatibility.

subscription factor = API cost (USD) / (subscription cost (USD) × window_days / 30)

The factor is normalized to the selected cost window, so windows remain comparable. 1x means API-equivalent cost matches the subscription cost for that period. 10x means API-equivalent cost is ten times the subscription cost.

Token details (input, output, cache creation, cache read, total) are shown per provider in the live view, scoped to the active cost window. For the full calculation model, see docs/how-quotabar-calculates.md.

npm install

npm run dev:watch is the fastest inner loop: it runs tsc --watch and nodemon in parallel. TypeScript compiles on every save; Electron restarts automatically ~2 seconds after a .ts change. For renderer-only changes, skip the restart entirely with location.reload() in DevTools.

src/
|- main/       Electron lifecycle, tray menu, notifications, autostart, backfill
|              └─ modelsData.ts  per-model aggregation (backfill + live-tail merge)
|- providers/  Claude and Codex live usage providers
|- auth/       Credential parsing, JWT helpers, token refresh
|- usage/      Re

Read the rest on GitHub