A Claude Code usage tracker in the MacBook notch
Notchmeter shows Claude Code's 5-hour session window, its weekly window and the per-model weekly limits Anthropic publishes beside the notch, each with a pace tick, a projection and its reset, and what your local sessions would have cost at API list prices. It reads them from Claude Code's own status line and the login Claude Code already keeps on your Mac. It never signs in and never stores a token.
macOS 15 or later · Apple silicon or Intel · no account, ever
What Notchmeter shows for Claude Code
The rings beside the notch carry the figure; hover them and the panel opens on the Claude card.
- Session and Weekly: the 5-hour and 7-day windows as Anthropic reports them, with the used share, a pace tick where an even burn would be right now, a projection (“~58% left at reset” or “Runs out in 2h”), and the reset as a countdown or an exact time.
- Per-model weekly limits (Opus, Sonnet, Fable…), each as its own meter, and an All models window tagged inferred: where Anthropic's own weekly window covers the same period and reset as every per-model window and reads no lower than any of them, that figure, adopted exactly and never recomputed; otherwise the highest of the model windows, never their mean, with the soonest reset.
- Extra usage against its monthly cap, on an account that has it, and a line the first time it rises in a month.
- Cost: today, yesterday, the week, the month, 30 and 90 days, by model and by project, from this Mac's own transcripts at Anthropic's published rates; and a burn line when the last hour ran hot.
- Context: with the status line installed, a thin arc around the Claude ring shows how full the session's context window is, and the card says “Context 62% · Opus · $1.23 this session”.
- Sessions: every running session with its title, branch and terminal; one running in a terminal is listed without the hook, marked as found without it. The optional hook adds the live state: a dot on the ring while one waits for you, each finished turn and a refresh the moment it ends, and Allow, Deny or the answer to a question under your thumb.
- The drain: “12% → 61% in the last hour” under a meter that moved, from an append-only log of every read, and a 24-hour sparkline.
Where each figure comes from
Every window carries its source, and the card names it. Nothing here is computed from a subscription price, a seat count or a guess.
| Figure | Source | Notes |
|---|---|---|
| Session, Weekly | Claude Code's status line (rate_limits.five_hour, seven_day) while its last report is under three minutes old; otherwise GET https://api.anthropic.com/api/oauth/usage, on a five-minute cadence | The card says From Claude Code's status line when that is the source. The status line is local and costs no request. |
| Per-model weekly (Opus, Sonnet, Fable…) | The usage endpoint's limits[] of kind weekly_scoped (older payloads: seven_day_opus, seven_day_sonnet) | The status line has no field for them, so beside a fresh status line the endpoint is still read every thirty minutes for these alone. |
| Extra usage | The usage endpoint | Shown against the monthly cap the endpoint reports; never inferred. |
| Cost | This Mac's transcripts under ~/.claude/projects/, priced at the rates on Anthropic's pricing page read 2026-09-24, the table built into the app, which a daily price catalog (on by default) can add a model to or update between releases: five token buckets per model, ×1.1 when a response reports inference_geo: "us", web searches at $0.01 each | An estimate at list price, and labelled local transcripts. On Pro, Max, Team or Enterprise nothing here is a bill. |
| Context, session cost, model | The status line | Only while Claude Code is sending reports; never estimated. |
| Sessions, waits | The optional hook; without it, the sessions running in a terminal, from the process, Claude Code's own session file and the end of its transcript, each marked as found without the hook | Documented events only; a wait is claimed only for an event that means the agent is asking you. |
The login comes from the Keychain item Claude Code-credentials (read with prompts off, then through /usr/bin/security), else ~/.claude/.credentials.json, else CLAUDE_CODE_OAUTH_TOKEN. A setup on an API key, Bedrock or Vertex has no plan window, and the card says so rather than drawing an empty bar. The token goes only to api.anthropic.com, as Authorization: Bearer with User-Agent: Notchmeter/<version>, in the one read-only request above; it is never refreshed, stored or forwarded. Because only Claude Code renews it, a Mac account where Claude Code has not run for a while holds a token past its expiry; the card then keeps its last reading under one grey line, Not updated since and the time, until claude runs there again.
The usage endpoint is undocumented: the channel Anthropic documents for these figures is the status line. With Also poll Claude's usage endpoint off (Settings › Assistants › Claude Code) the status line is the only source and no request goes to Anthropic at all. Anthropic's rate-limit headers arrive only on inference requests, which Notchmeter never makes, so it does not read them; the reasoning is in Why there is no header fallback, and the terms question is answered plainly in docs/privacy.md.
What it says to do about it
Every other meter tells you how much. The Advice strip under the Cost card is worded as an instruction, and each rule is a pure function pinned by tests.
Questions
Does Notchmeter need my Anthropic login?
No. It reads the login Claude Code already keeps on this Mac, the Keychain item or the credentials file, and sends that token only to api.anthropic.com in the same read-only status request. It never signs in, never refreshes the token and never stores it. Switch accounts in Claude Code and the notch follows on its next read.
Is the cost figure my bill?
No. On a Pro, Max, Team or Enterprise plan nothing on the card is a bill: the figure is the API-equivalent value of the work your sessions did, at list price, computed from this Mac's transcripts the same way Claude Code's own /usage session figure is. On an API key it is an estimate at list price, and a contracted modelPricing table in Claude Code's settings is honoured. Every rule and every known divergence is in docs/accuracy.md.
Why does the cost not match my session and weekly percentages?
Because they measure different things. The session and weekly figures are Anthropic's own, account-wide, from the usage endpoint or the status line, so they match what Claude Code's /usage shows at the same moment. The cost is built from this Mac's transcripts alone: work on another Mac or on claude.ai counts against the window but never appears in the cost.
Does it work without the status line or the hook?
Yes. Without them the usage endpoint is read every five minutes and the meters show the same session, weekly and per-model figures, and sessions running in a terminal are still listed, each marked as found without the hook. The status line makes the session and weekly figures local and instant and adds the context gauge; the hook adds the live state (waits, finished turns and a refresh the moment a turn ends), sessions outside a terminal, and answering from the notch. Each has its own switch in Settings.
Does it make inference requests or use up my limit?
No. Notchmeter never calls the messages endpoint. Anthropic's rate-limit headers arrive only on inference requests, so it does not read them either; the one request it makes is the usage read, which consumes no model capacity. Why there is no header fallback sets out what was checked and when.
Is reading the usage endpoint allowed by Anthropic's terms?
Anthropic's published policy says consumer OAuth is designed to support ordinary use of Claude Code and other native Anthropic applications, and Notchmeter is neither; it says so plainly, names itself in every request, and never touches an inference endpoint. With Also poll Claude's usage endpoint off the status line is the only source and no request goes to Anthropic at all. The full quotes and the app's reading of them are in docs/privacy.md and on the Terms page.
Install it
macOS 15 Sequoia or later, Apple silicon or Intel. Signed, notarised, and it updates itself. Free forever, MIT licensed.
Notchmeter is a Mac app. There is no Windows or Linux version; if you want a Windows one, the Windows issue is where to say so. How every figure is built, with its source and its date: docs/accuracy.md.