Claude Usage
Setup guide
Before you start
You need macOS 14 or later and a working Claude Code install that you have signed into at least once. Claude Usage reads only what Claude Code already stores on your Mac — it has no account of its own and nothing to sign up for.
Install
With Homebrew:
brew tap saeedkolivand/tap
brew trust --cask saeedkolivand/tap/claude-usage
brew install --cask claude-usage
The trust step is not optional. Since Homebrew 6.0,
third-party taps must be trusted explicitly before Homebrew will
evaluate their code — a response to a real incident where a
compromised tap was used to ship malware. Trusting one cask by name
is the narrowest scope; brew trust saeedkolivand/tap
would cover everything in the tap, now and in future.
Prefer a download? Grab the .dmg from
Releases
and drag the app to Applications. Builds are ad-hoc signed rather
than notarized, so macOS quarantines them and will call the app
damaged on first launch. The cask clears that for you; after a manual
install, run:
xattr -dr com.apple.quarantine "/Applications/Claude Usage.app"First launch
Claude Usage has no Dock icon — it lives in the menu bar. On first run two things happen:
-
macOS asks for Keychain access. Claude Code keeps
its access token in the login Keychain, and reading it from another
app needs your say-so. Choose Always Allow so it
stops asking. Decline and the limit gauges show
--; tokens and cost still work, since those come from transcripts on disk. - History backfills once. The app reads your whole transcript archive to seed the 14-day chart, which can take a few seconds on a busy machine. It happens once, in the background.
Add the widget
Right-click the desktop, choose Edit Widgets, find Claude Usage, and drag out the size you want. The app must have run at least once for the widget to appear.
A freshly placed widget shows a placeholder for up to a minute. That is expected: macOS creates the widget's sandbox container the first time it runs, and the app fills it on the next poll.
Not showing up at all? Run killall chronod to make macOS
rescan its widget extensions.
Blank after updating from 0.2 or earlier? Remove the
widget and drag out a fresh one. Widgets became configurable in 0.3,
and macOS cannot migrate an already-placed widget across that change
— it fails the timeline request outright
(Intent configuration is required but was not provided).
A widget configured under 0.3.0 or 0.3.1 likewise needs its profile
picked again; the stored selection changed format in 0.3.2 and an old
one reads back as unset, so the widget quietly shows the default
account.
Configure a widget
Right-click any placed widget and choose Edit Widget. Each one is configured separately, so you can place several with different scopes.
Profile
Which Claude account this widget shows. Most people have one and can ignore this.
Project
Leave it empty for the whole account. Pick a project and the widget narrows to that working directory: today's tokens and cost, its share of the week, and a 7-day chart.
A project-scoped widget has no limit gauges, and that is deliberate rather than missing. The 5-hour and weekly percentages are reported per account, so there is no such thing as a single project's limit.
Settings
Open them from the menu bar popover.
Profile
Which account the menu bar itself shows. A profile is a Claude Code
config folder — one logged-in account. Relocating that folder with
CLAUDE_CONFIG_DIR is the only way Claude Code supports
more than one, so that is what the list looks for:
~/.claude, anything beside it whose name starts with
.claude, and folders you add with
Add Folder…. A folder counts when it contains a
projects directory.
One caveat on macOS. Claude Code names each profile's
Keychain item after the config folder it was signed into:
Claude Code-credentials for the default
~/.claude, and
Claude Code-credentials-<8 hex> — a hash of the
folder path — for anything relocated with
CLAUDE_CONFIG_DIR. That hash is taken over the
literal string you exported, so
~/.claude-work, $HOME/.claude-work and
/Users/you/.claude-work/ are three different items. The
app tries the plausible spellings and shows the one it looks for
beside Folder in Settings; if yours is unusual the
profile reports no token. Tokens and cost still work either
way, since those come from transcripts on disk.
Menu bar shows
Whether the number in the menu bar is the 5-hour window or the
weekly one. Past your red threshold it gains a
! prefix — menu bar items are drawn as template images,
so colour would be stripped and a symbol is the only signal that
survives.
Amber and Red thresholds
Where the gauges change colour, defaulting to 50% and 80%. They also travel to the widgets, so everything agrees.
Open at login
Registers the app as a login item. This needs a properly signed build; on an ad-hoc one the toggle reports the error rather than silently flipping back.
Updates
Shows the running version and whether a newer release exists,
checking GitHub four times a day. Check Now forces
one. Nothing is ever downloaded or installed for you — update with
brew upgrade --cask claude-usage, or the link to the
release notes.
User-Agent (Advanced)
Sent to the usage endpoint. It must begin with
claude-code/ or the API serves a heavily rate-limited
bucket. Only worth touching if the version string ever goes stale.
If something looks wrong
"Sign in with Claude Code"
No usable token. Run claude once and sign in. On a
non-default profile, compare the Keychain name in
Settings against what you actually have:
security dump-keychain | grep -o '"svce"<blob>="Claude Code[^"]*"' | sort -uNo match means the folder path was spelled differently when you signed in — see the profile caveat above.
"No connection", or numbers marked outdated
The usage endpoint didn't answer. The app keeps showing the last good figures and labels them outdated rather than blanking the display. It retries on its own; Refresh forces one immediately.
"No Claude Code data found"
No config folder with a projects directory was found. If
yours lives somewhere unusual, add it with
Add Folder… in Settings.
Tokens and cost look low
Cost is computed from token counts in your local transcripts, so it only covers what Claude Code wrote to disk. On Pro and Max plans it is notional equivalent API spend, not money you were charged.
Still stuck?
Open an issue on GitHub.