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. 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.

Sound familiar?

• 🧱 You're deep in a refactor and Claude Code just… stops. Out of quota, no heads-up — now you're blocked and you didn't even see it coming.
• ❓ No idea how much of your 5-hour or weekly limit is left. You're flying blind until you hit the wall.
• 🔁 A CLI answers — but only when you stop and run it. usage never makes you ask; the number's already in the corner of your eye.

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.

🚀 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.

✨ What you get

• See it without looking for it. Your quota lives in the menu bar, color-coded — green to red — so the warning level reads in a glance, no click required. Click only when you want the full breakdown.
• Never re-explain your progress again. Open a new Claude Code session and usage hands your last progress straight to the AI — no /resume, no recap, and no dragging a bloated old conversation back just to continue. Fully local, off by default. Learn more.
• Find out where your tokens leak — without asking. A daily background health check scans your local session logs for avoidable waste — the same files read over and over, bloated sessions, oversized command output. When it finds something worth fixing, the new-conversation handoff above gains a one-line heads-up; say "show me" and the AI walks you through the findings and how to fix them. Ships with the Progress Concierge, fully local.
• Warned before the wall, not at it. A system notification when you're nearing a threshold, run out, or recover — so you wrap up on your terms instead of getting cut off mid-sentence. Fully local, off by default.
• Know where your tokens actually go. HTML deep reports with token & cost trends and per-project rankings — shareable with your team.
• Make it yours. 10 switchable panel themes, from a clean light card to a World Cup broadcast HUD. Only use one of Claude Code / Codex? Hide the other from the menu bar and every panel with a single toggle.
• In your language, automatically. UI in Traditional Chinese, Simplified Chinese, English, Japanese, and Korean, following your system setting.

🔒 Privacy & data sources

• Usage numbers are read only from the local log files Claude Code / Codex leave on your machine — it never calls the Anthropic / OpenAI API and never reads the Keychain (macOS's built-in password vault).
• The only two times it goes online: fetching a public model-pricing table to estimate cost (falls back to built-in prices if that fails), and occasionally checking GitHub for a new version. Neither involves your usage data, and nothing is ever uploaded.

Requirements

• macOS
• Claude Code or Codex has been used at least once so local usage data exists
• (Only if running from source) Python 3.13

📦 Install

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.)

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 (or anywhere you like)
3. First launch: in Finder, right-click usage.app → Open → confirm Open
4. Click the usage icons in the top-right menu bar to see your usage

⚠️ 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.

Homebrew

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 usage once, then the cask command above.

Same first-launch right-click → Open as above (to pass Gatekeeper).

First launch: set up the status line

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:

• The Claude / Codex usage icons and percentages in the top-right menu bar
• Click it for the Claude Code / Codex usage cards
• If it shows --, 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 restart

Once 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.

Troubleshooting

The "Fix" column distinguishes three kinds of users — find yours first:

• .app users — downloaded usage.app.zip from GitHub Releases, unzipped, dragged usage.app to /Applications, double-click to launch like any Mac app. No Terminal, no Python.
• LaunchAgent users — cloned the source and ran ./scripts/install-launchagent.sh so macOS auto-starts usage on login.
• Source users — cloned the source and run 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.