usage

Your quota, where your eyes already are.

Claude Code & Codex usage, always in the macOS menu bar. A command tells you when you ask — usage tells you without being asked.

繁體中文 · English  |  💬 Discussions  |  🌐 Landing page

usage keeps your Claude Code and Codex quota pinned to the top-right of your screen, color-coded so the warning level reads at a glance. Every number is read passively from local files — it never calls the Anthropic / OpenAI API and never reads the Keychain, meaning the monitor itself never adds to your token usage.

💡 Why usage?

• 🧱 No more surprise blocks. You're deep in a refactor and Claude Code just stops. Out of quota, no heads-up — now you're blocked.
• ❓ No more flying blind. You have no idea how much of your 5-hour or weekly limit is left until you hit the wall.
• 🔁 Zero friction. A CLI answers you only when you stop and ask. usage answers all questions at a glance: the number is already on your screen, color-coded, no command to run, no page to open.

🚀 Quick Start

brew install --cask aqua5230/usage/usage

It lands in your Applications folder automatically → right-click Open once (to pass Gatekeeper) → click the menu bar icons. Prefer a direct download or want every detail? See Install below.

✨ Features

• 👁️ Always-on Monitor: Your quota lives in the menu bar, color-coded (green to red). Click only when you want the full session, weekly, and per-project breakdown.
• 🧠 Progress Concierge: Open a new Claude Code session and usage hands your last progress straight to the AI — including your last request, uncommitted changes, and unfinished todos. No /resume, no recap. Fully local, off by default.
• 🤐 Terse Mode: A menu-bar toggle asks Claude Code and Codex to answer more tersely for the session, saving output tokens while keeping code and error messages byte-exact.
• 🩺 Token-waste Health Check: A daily background diagnosis scans your logs for waste — repeated file reads, polluter directories, noisy Bash output. If it finds issues, a one-line heads-up appears; say "show me" and the AI walks you through fixes.
• 📊 Deep HTML Reports: Instant, shareable HTML deep reports showing daily/weekly token trends, project rankings, and cost. Includes an AI Tool Update Digest summarizing recent changes, and a Year in Review featuring a contribution heatmap and "Wrapped" summary.
• 🎨 10 Visual Themes: Switch between stunning panel styles: Classic, Matrix, Windows 95, Newspaper, Cloud Observation, Midnight Aquarium, Prism Arcade, Black Hole, World Cup 2026, and Lepidoptera (blueprint).
• 🧑‍💼 AI Talent Market: Bring a ready-made AI team into Claude Code. Browse and install curated subagent personas into ~/.claude/agents/ instantly. Runs fully locally via the bundled CLI.
• 🐉 Summon Spirits: Add a tiny animated white silhouette beside your usage percentages — a phoenix for Claude, a dragon for Codex. It accelerates dynamically as your token burn rate climbs.
• 🔔 Context Nudges & Notifications: When your context window hits 70%, the status line nudges you to /clear or /compact to prevent token waste. You can also opt-in to system notifications for quota limits and recoveries.
• 🌍 Automatic Localization: Beautiful UI translated into Traditional Chinese, Simplified Chinese, English, Japanese, and Korean, automatically matching your system settings.
• 💻 TUI & CLI: Love the terminal? Run the rich TUI dashboard with python3 main.py --tui, or generate deep analytics with python3 usage_cli.py report.
• 🎛️ Hide Sections: Only use one tool? Hide the Claude Code or Codex section from the menu bar and panels completely with a single click.

🔒 Privacy & Data Sources

• Usage numbers are read only from local log files on your machine.
• It never calls the Anthropic / OpenAI API and never reads the Keychain (macOS's password vault).
• The only network activity: fetching a public model-pricing table to estimate cost (falls back to built-in prices offline) and occasionally checking GitHub for a new version. Nothing is ever uploaded.

⚙️ Requirements

• macOS
• Claude Code or Codex has been used at least once (so local usage data exists).
• (Source runs only) Python 3.13.

📦 Install

1. Homebrew (Recommended)

Installing via Homebrew means a single brew upgrade --cask usage keeps it current.

brew install --cask aqua5230/usage/usage

(First launch: right-click usage.app in Finder → Open to pass Gatekeeper).

2. Download the App

1. Download the latest usage.app.zip from the GitHub Releases page.
2. Unzip it and drag usage.app into your Applications folder.
3. First launch: in Finder, right-click usage.app → Open → confirm Open.

First Launch: Set Up the Status Line

If you've used Codex, usage picks up its history automatically. For Claude Code, click the "Set Up Status Line" button in the app popover to install the sync hook. Restart the relevant tool afterward (fully Cmd+Q Claude Code and re-open it).

Once set up, the bottom of the Claude Code window will show a status line like this:

🎨 Panel Themes

Switch between 10 visual themes directly from the UI:

🛠️ Troubleshooting

If the menu bar shows --, it's usually not broken — there's just no local data yet.

Symptom	Likely cause	Fix
Menu bar shows --	No data yet, or Claude Code hook not refreshed	Run one Codex conversation. For Claude Code, click "Set Up Status Line" or run python3 main.py --setup
Accidentally hit "Quit"	Process terminated	Launch usage.app from Spotlight / Applications, or run launchctl start com.lollapalooza.usage
Status says "N minutes stale"	Claude Code isn't running	Open Claude Code and let it run
Codex section is empty	No Codex history found	Run a Codex conversation to generate logs
Today's cost shows $0.00	Model pricing missing	Delete ~/.claude/pricing_cache.json or check USAGE_DEBUG=1
App won't open	macOS Gatekeeper blocked it	Right-click usage.app in Finder → Open
App crashes immediately (arm64)	py2app bundling bug in older versions	Upgrade to v0.11.1 or newer

⚖️ Comparison

Feature	usage	ccusage	TokenTracker
Always on screen	✅	—	✅
macOS menu bar	✅	—	✅
Claude Code & Codex usage	✅	Claude only	✅
HTML deep reports & UI	✅	✅	—
AI Talent Market	✅	—	—
Progress Concierge & Terse Mode	✅	—	—
Token-waste Health Check	✅	—	—
Zero API calls	✅	✅	✅
Open-source license	AGPL-3.0	MIT	—

💻 Run from Source / Develop

Want to run the terminal TUI, configure custom agents, or build the app yourself? Check out the development docs.

📄 License

Licensed under AGPL-3.0-only (see LICENSE). If you fork or redistribute a modified version, please credit the original author and link back to: https://github.com/aqua5230/usage

📈 Star History

❤️ Support

If usage has ever saved you from a surprise quota cutoff mid-task, a ⭐ helps other developers find it.

Consider buying me a coffee ☕