by aqua5230
macOS menu bar app pinning Claude Code & Codex quota, tokens, and cost to your screen. Local-only, zero API calls. HTML reports, 9 themes.
# Add to your Claude Code skills
git clone https://github.com/aqua5230/usageLast scanned: 6/10/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-06-10T08:08:30.473Z",
"npmAuditRan": true,
"pipAuditRan": true
}usage is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by aqua5230. macOS menu bar app pinning Claude Code & Codex quota, tokens, and cost to your screen. Local-only, zero API calls. HTML reports, 9 themes. It has 219 GitHub stars.
Yes. usage passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/aqua5230/usage" and add it to your Claude Code skills directory (see the Installation section above).
usage is primarily written in Python. It is open-source under aqua5230 on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh usage against similar tools.
No comments yet. Be the first to share your thoughts!
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. One click opens Session, Weekly, per-project usage (today / 7-day / monthly), and today's token cost. Every number is read from local files Claude Code and Codex already write — it never calls the Anthropic / OpenAI API and never reads the Keychain, so the monitor itself never adds to your usage.
usage answers all three at a glance: the number is already on your screen, color-coded, updated passively from local logs — no command to run, no page to open.
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.
/resume, no recap, and no dragging a bloated old conversation back just to continue. Fully local, off by default. Learn more.Two ways to install — pick whichever suits you. Steps for both are below. (In a hurry? The one-line Homebrew install is in Quick Start above.)
usage.app.zip from the GitHub Releases pageusage.app into your Applications folder (or anywhere you like)usage.app → Open → confirm Open⚠️ Step 3 is needed because the app isn't signed with an Apple Developer certificate, so macOS Gatekeeper (the built-in feature that blocks unfamiliar programs) blocks the first launch; once you right-click → Open to allow it once, double-clicking works normally afterward.
Installing via Homebrew (the macOS package manager) means a single brew upgrade --cask usage keeps it current. It's shipped as a cask (Homebrew's format for GUI apps), so it drops usage.app straight into your Applications folder — no manual move needed. The Quick Start one-liner above already installs it — that command's full path auto-adds the tap for you, so one line is all you need. Prefer to run the two steps explicitly?
brew tap aqua5230/homebrew-usage
brew install --cask aqua5230/usage/usage
Upgrading from an older release that installed via a formula? Run
brew uninstall usageonce, then the cask command above.
Same first-launch right-click → Open as above (to pass Gatekeeper).
The first time you open usage, if you've already used Codex, it automatically picks up your Codex history and shows it — no setup needed. If you use Claude Code, the popover (the small window that pops up when you click the icon) may show a "Set Up Status Line" button — click it to install the hook (a small script that runs every time Claude Code refreshes its status line) that syncs your usage to the menu bar.
Restart the relevant tool afterward: restart Codex once; if Claude Code was configured too, fully quit Claude Code (Cmd+Q) and re-open it so the data lands on disk.
Then you'll see:
--, it's usually not broken — there's just no local usage data yet: Codex needs one conversation first, and Claude Code needs the status line set up plus a full restartOnce set up, the bottom of the Claude Code window will show a status line like this — 5h / 7d quota bars, context usage, session duration, current model — all on one line:
To toggle the status line on / off later (e.g. you want to see Claude Code's native status line), click the CLI ✓ button in the menubar popover's "Projects" section toolbar.
Running from source, or want to install via the command line? See the development docs.
The "Fix" column distinguishes three kinds of users — find yours first:
usage.app.zip from GitHub Releases, unzipped, dragged usage.app to /Applications, double-click to launch like any Mac app. No Terminal, no Python../scripts/install-launchagent.sh so macOS auto-starts usage on login.python3 main.py manually in Terminal each time.Seeing
--? Don't reinstall just yet — in the vast majority of cases there's simply no local usage data yet, and it appears after one conversation.
| Symptom | Likely cause | Fix |
|---|---|---|
Menu bar shows -- |
No Codex rate_limits yet, or the Claude Code hook has not refreshed |
Run one Codex conversation first. For Claude Code integration, .app users click "Set Up Status Line"; Source users run python3 main.py --setup |
| Accidentally hit "Quit", usage icons disappeared from the menu bar | "Quit" fully terminates the usage process; you have to relaunch it | .app users: press Cmd+Space for Spotlight, type usage, hit Enter; or double-click usage.app from /Applications. LaunchAgent users: run launchctl start com.lollapalooza.usage in Terminal. Source users: run python3 main.py in Terminal again |
| Status says "N minutes stale" | Claude Code isn't running | Open Claude Code and let it run; it updates the file on its next status refresh |
| Codex section is empty | ~/.codex/sessions/ doesn't exist or has no rate_limits events yet |
Run a Codex conversation to generate log entries |
| Today's cost shows $0.00 | Model name doesn't match the pricing table, or pricing download/cache failed | Delete ~/.claude/pricing_cache.json to force a re-fetch; or run with USAGE_DEBUG=1 for details |
| App won't open (blocked by macOS) | Gatekeeper blocks unsigned apps | Finder → find usage.app → right-click → Open → confirm Open |
| App crashes immediately on launch (macOS Sequoia / arm64 |