Claude Code

UsageNow gets Claude Code information from two separate sources:

1. Local activity — always available when Claude Code is enabled. Tokens, requests, most recent model, and plan, read from files on your Mac.
2. Usage limits — experimental and off by default. Your 5-hour and weekly limits, fetched from Anthropic with your existing Claude Code sign-in.

Requirements#

• Claude Code installed on your Mac
• Signed in to Claude Code, and used at least once on this Mac

Local activity#

UsageNow reads safe, structured metadata from Claude Code’s local session data in ~/.claude/projects to show:

• tokens today — tokens recorded since midnight, including cached input
• requests — model responses recorded today
• most recent model
• activity by model — see Models today

It extracts only timestamps, identifiers, model names, and token counts. UsageNow ignores:

• prompt contents
• assistant responses
• source code
• file contents

Plan#

Your plan — Pro, Max, Max 5x, Max 20x, Team, or Enterprise — comes from the account profile Claude Code caches in ~/.claude.json. Team and Enterprise also show your seat, such as Team · Premium. UsageNow reads only the fields that state the plan. If the plan isn’t stated there, no badge is shown; the plan is never inferred from the models you use.

Experimental usage limits#

Claude Code does not currently expose subscription limits through a supported local API. UsageNow can optionally read the existing Claude Code access token from macOS Keychain and query Anthropic’s usage endpoint — the same information Claude Code itself shows with its /usage command.

Turn it on#

1. Make sure Claude Code is enabled in Settings › Providers.
2. Go to Settings › General and turn on Fetch Claude usage limits.

Limits then appear in the Claude Code section: usually a 5-hour window and a weekly window, and sometimes a weekly window for a single model family such as Opus.

What UsageNow does with your sign-in#

When the setting is on, UsageNow:

• reads the keychain item Claude Code created, only after you turn the setting on
• receives it through a pipe straight into memory, and extracts only the access token and its expiry time
• keeps the token in memory only
• sends it only to api.anthropic.com, to request your usage
• asks for limits at most once every five minutes during automatic refreshes, one request at a time

UsageNow never:

• refreshes your Claude Code sign-in
• modifies or deletes the keychain item
• stores the token or any other Claude Code credential
• logs the token
• uses the refresh token

When you turn the setting off, UsageNow forgets the token and any cached limits.

Keeping your session fresh#

Claude Code’s access token lasts a few hours. Claude Code renews it when it runs; UsageNow never does. If you mostly use the Claude desktop app, note that it keeps its own sign-in and doesn’t renew the one in your keychain.

When the token has expired, use Claude Code once — for example, launch claude in Terminal:

claude

You don’t need to come back and choose Try Again. While the saved sign-in is expired, UsageNow checks only when the keychain item last changed — which reads no secret — and reads the token again as soon as Claude Code has saved a new one, on its next refresh.

An expired sign-in doesn’t empty the display, either. The last limits UsageNow read stay for a day, marked stale with Updated … ago and with Refresh Claude Code from Terminal to view usage limits. beneath them, even if you quit or update the app in between, so the menu bar and the widget still show yesterday’s numbers in the morning — and the popover says they're old and how to bring them up to date. A successful read replaces them. The stored copy holds only percentages and reset times, and turning the setting off removes it.

Limits you hit#

Separately from the setting above, when Claude Code stops a request because a limit was reached, it records which window and when it resets. UsageNow reads that from the session transcript and shows the window as used up until then. This needs no sign-in and works even with the experimental setting off, or when you use Claude Code inside the Claude app.

A window that reset since UsageNow last read your limits stays on screen without a percentage — “5-hour — · Reset Mon 22:59 · not updated since” — because nothing local says how much of the new window is used. Run claude in Terminal to bring the live percentage back.

States#

When usage limits aren’t available or can't be refreshed, UsageNow says why in one line — in the Claude Code section and under the setting in Settings › General. When you need to act, the line appears even beside last known values; a passing outage is mentioned only once those values are more than 10 minutes old:

In every case, local token, request, model, and plan information stays visible when it’s available, and limits read earlier stay on screen as stale for a day. Usage limits are the only part that depends on the experimental source.

More than one account#

If you keep a second Claude Code account in its own folder — running Claude Code with CLAUDE_CONFIG_DIR pointing at it — add it in Settings › Providers › Claude Code › Add Account… and choose that folder. It appears as its own section, such as Claude Code · Work, with the plan, activity, and 30-day history from that folder.

Its limits appear when Claude Code records reaching one in that folder's sessions. The experimental usage limits source reads only the default account's sign-in, and never another account's. See Accounts.

Where UsageNow looks#

UsageNow looks for Claude Code data in ~/.claude and ~/.claude.json, or in the folder set by CLAUDE_CONFIG_DIR, and in the folder of each account you added. It also recognizes the claude executable in ~/.local/bin, ~/.claude/local, /opt/homebrew/bin, and /usr/local/bin.