Installation

Use a package runner:

npx agent-burn@latest summary --value
pnpm dlx agent-burn@latest summary --value
bunx agent-burn@latest summary --value

The package exposes two binaries:

• agent-burn
• burn

Example:

burn harness claude --value

Nix

The flake exposes the renamed package and app:

nix run github:Melvynx/agent-burn -- summary --value
nix build github:Melvynx/agent-burn#agent-burn

macOS app

Codex and Claude quotas are collected every minute by a macOS background agent, even after the app quits. Enable or disable this in Settings → Background quota history; allow background activity in macOS Settings if requested. The agent reads live provider counters independently of full spend reports and cached mode. Collection resumes after sleep or login. During outages, the last valid reading and its timestamp remain visible; missed measurements are not fabricated.

The first public Mac download is awaiting Apple notarization. Check download availability. Once released, unzip it and move Agent Burn.app to Applications. The signed, notarized download supports Apple Silicon and Intel on macOS 14 or later. It bundles the CLI, so Node.js is not required.

The app automatically checks for signed updates with Sparkle. Change this in Settings or choose Agent Burn → Check for Updates…. Release archives, checksums and source are public on GitHub.

To build from source with Xcode and the Rust development environment, run:

just macos::run

This builds apps/macos/dist/Agent Burn.app with a bundled native CLI. The app is locally signed for development. The public download is separately signed and notarized.

Use the flame in the menu bar to switch between General, Codex, Claude, and Cursor. All-time spend follows the latest all-time daily snapshot. Filtered period caches only fill dates the archive does not already have, so a today row cannot double a day already reported by all.

The Codex and Claude tabs focus on remaining quota, reset time, and the forecast. They also show average $ / % and tokens / $ from live used percent crossed with logged API-equivalent spend and tokens. Expand Usage details for spend and models; saved readings and update failures stay visible beside the quota. Choose Settings → Menu bar quota (or the percentage next to the flame) to show Codex, Claude, or Cursor remaining usage in the menu bar and window toolbar. Enable Settings → Startup → Launch at login to start the app when you sign in to macOS. If approval is required, use the displayed button to open macOS Login Items settings. Disable the option to stop launching at login.

Enable Settings → Appearance → Menu bar only to hide Agent Burn from the Dock and Command-Tab. The choice is remembered between launches; disable it to show the app again. The dashboard and Settings remain available from the menu bar. Choose Open dashboard for full harness details and a General tab with WTD, MTD, YTD, and rolling week/month, Reset to date, and All time filters. Cursor shows promotional-credit remaining over time when those credits are burning, otherwise daily spend with All models and Cursor models filters, plus included allowance and billing-cycle dates when its account API supplies them. Settings control the native CLI path, Codex source folders, cached pricing, and refresh interval. The app includes the standard ~/.codex folder alongside the launching profile and stores aggregate report snapshots locally for reopening. Changed reports are kept in usage-journal.json so daily graphs and model totals can be rebuilt if both report-cache.json and its .bak are unreadable. Quota screens count scheduled and possible resets. Daily spend and token totals are retained without expiration in ~/Library/Application Support/Agent Burn/metrics-history.json, with a previous-version .bak recovery copy. Date filters and charts use this archive after source logs disappear. Period changes show saved totals immediately while missing detail refreshes in the background. Recent reports are reused, the selector stays enabled, and harness tabs read only their selected source. History and recovery files are maintained automatically without dashboard controls. All-time snapshots replace days they still report. Filtered period caches only fill missing dates. Copy this file off the Mac for disaster recovery. Cursor begins at its current billing cycle; model and token-category detail still reflects available source data. Its native toolbar, tables, and menu-bar indicator follow the system appearance. Forecasts estimate average consumption during the current quota cycle. Recorded history builds as the app refreshes and stays on this Mac. Unavailable limits are shown explicitly.

The app uses the existing JSON reports and your local CLI configuration. No additional sign-in is required by the app.