claude-usage-tray

claude-usage-tray is a tiny application that lives in your menu bar on macOS or your system tray on Linux, and it reports the status of your Claude quotas and sessions. The numbers come straight from the Claude CLI itself, so there are no cookies to copy and no awkward browser hacks to keep alive. It installs a small hook on the Claude CLI, and from then on, whenever you use Claude normally, fresh numbers flow to the tray and keep it current. Other tools resort to tricks like impersonating the Claude CLI, which can get an account banned, since Anthropic disallows the practice.

Jump to installation →

The app can also notify you at the moments that matter: when you cross usage thresholds you choose, on the 5-hour window, the weekly one and each per-model weekly limit, and when those quotas reset. All of it is configurable from the tray menu itself.

There is no window and no dashboard to keep open. Just a small gauge that changes color as you get closer to the limit, and a menu when you want the details. Green means you have room, red means wrap it up.

🔒 It never talks to the Claude Website or Anthropic APIs

This is the part worth reading slowly.

The tray never reads your Claude credentials, never touches your OAuth tokens, and never contacts Anthropic or the Claude website at all. There is no account to create and nothing to log into.

Here is the whole data flow. Claude Code already computes your usage numbers and hands them to whatever you have configured as your statusline. One command wires this tool into that statusline, where it quietly copies those numbers to a small file on your machine. The tray reads that file. That's it.

Your own statusline keeps working exactly as before. If the tray ever fails to write its file, your statusline still prints what it always printed, because the piece that runs inside Claude Code is built to stay out of the way and never fail loudly.

The only network request the program can make is an optional update check, once a day, against the GitHub releases API. It is anonymous, it sends nothing but the program name and version, and it only reads the latest release tag. Turn it off in Settings > Check for updates and the program makes zero network requests, ever.

🧭 Reading the icon

The icon is a small gauge, and it tells you two things at once.

• The outer arc is your 5-hour session, sweeping clockwise as you use it up.
• The dot in the middle is your weekly usage.
• The color is the warning: green under 50%, yellow under 75%, orange under 90%, red at 90% and above. Both parts use the same bands.
• No dot in the middle means your account has no 5-hour limit. The arc shows your weekly usage instead, and the menu skips the session row.
• A question mark in the middle means the numbers haven't been updated recently. You still see the last known reading, it just might not be current.
• A gray icon means there's no data yet, usually because the hook isn't installed.

On Linux, left-click the icon for a plain summary, something like "You've used 32% of your 5-hour session (resets in 3 h) and 33% of your weekly limit (resets in 2 d)." It appears briefly and disappears on its own. On macOS any click simply opens the menu, as menu bar items do, and the same numbers lead it.

Stale doesn't mean wrong, by the way. Reset times are real timestamps, so the countdowns stay accurate on their own. When a 5-hour window rolls over, the session percentage drops back to 0% even if nothing has reported in hours.

📦 Install

Every release ships binaries for x86_64 and arm64, on both Linux and macOS. The Linux ones are statically linked: no runtime dependencies, no glibc version to match. macOS additionally gets a real .app, which is the one to pick if you want notifications; it is a few blocks down.

Homebrew (macOS, recommended):

brew install --cask patrickdappollonio/tap/claude-usage-tray

The cask installs the full application into /Applications, which is the version with proper notifications, and it puts the claude-usage-tray command on your PATH too.

Homebrew (Linuxbrew):

brew install patrickdappollonio/tap/claude-usage-tray

The formula is Linux only and installs just the binary, which on Linux is the whole app. On macOS, use the cask above.

npm:

npm install -g @patrickdappollonio/claude-usage-tray

The npm package bundles the same prebuilt binaries for Linux and macOS. For a one-off run, use npx -y @patrickdappollonio/claude-usage-tray.

Debian, Ubuntu and derivatives:

curl -LO https://github.com/patrickdappollonio/claude-usage-tray/releases/latest/download/claude-usage-tray_<version>_linux_<arch>.deb
sudo dpkg -i claude-usage-tray_<version>_linux_<arch>.deb

Fedora, RHEL, openSUSE:

This is the beginning of the README. Read the rest at the original. Read the full README ↗