Notchmeter

Know which assistant is waiting, and whether you can afford the next task.

Every figure sourced, dated and tested — here is the document: docs/accuracy.md. Usage meters for Claude Code, Codex, Cursor, Gemini CLI, Antigravity, GitHub Copilot, Kimi Code and OpenCode, and the sessions they are running, that say what to do about the number, not only what it is.

Hover the rings beside the notch and the panel opens: cost, pace, projections and what to do next.

Your menu bar ran out of room three apps ago. This one doesn't take any. The rings live in the MacBook notch — or on any screen edge you prefer — small and dim while nothing needs you, and open into the full readout when you hover.

Answer Claude Code from the notch. When Claude Code stops for a permission, approve or deny it there; when it asks a multiple-choice question, pick the answer there; then jump back to the terminal window, tab or pane the session is running in. A request nobody answers falls back to the terminal's own prompt, as if the notch were not there, and each part has its own switch under Settings › Assistants › Sessions. What the hook sends for it, and how the channel fails open, is in docs/hooks.md.

Cursor works differently, so it gets its own treatment. Cursor's hooks report less than the other assistants': no task list, no plan, and no event that says it is waiting for you. Notchmeter reads the rest from Cursor itself. A plan appears on its chat's row when Cursor creates it, before it is built, with its to-dos, View Plan and Build, and the turn that builds it is named for the plan. Two switches under Settings › Assistants › Cursor, both off until you turn them on, let you answer it: Require notch approval for every command holds each shell command and MCP call for Allow or Deny in the notch, and Mirror Cursor's cards opens the notch on Cursor's own Run prompt and its switch-to-Plan-Mode card, with Cursor's buttons, and presses the one you pick in Cursor; a question Cursor asks is answered there too: pick a choice and press Continue, as in Cursor; one asked while Cursor's window is minimised or hidden still reaches the notch, shown with a button that brings Cursor back to answer it. A Cursor chat whose commands keep failing says May be stuck. What each one reads, and the Accessibility permission the second needs: docs/hooks.md.

notchmeter.com · Download · Guides · Support the project

What it shows

• Claude Code — the 5-hour session window, the weekly window and the per-model weekly limits, plus what your local sessions would have cost at API list prices.
• Codex — the session, weekly or monthly rate-limit windows Codex itself reads.
• Cursor — included plan usage and on-demand spend for the billing cycle, the way cursor.com's dashboard reads it. On the Sessions card, each chat's plan and to-dos, Build, and its approvals when you turn them on.
• Gemini CLI — the per-model quota Google meters for Gemini CLI.
• Antigravity — the session and weekly quota Antigravity's own panel shows, read under Antigravity's identity, so it can differ from Gemini CLI's on the same account.
• GitHub Copilot — the month's AI-credit allowance, or a legacy seat's premium requests.
• Kimi Code — the rolling five-hour window, the week and the monthly pools, the way Kimi Code's own /usage reads them.
• OpenCode — its spend and its sessions, read from OpenCode's own database with nothing to install, and on the Go plan a 5-hour, 7-day and 31-day meter computed on this Mac from your own turns at the prices and limits Go publishes, because Go offers no reading of its own, and labelled computed here.

Every meter shows a pace tick (where an even burn would be right now), a projection ("~67% left at reset" or "Runs out in 2h") and the reset time; a week is projected at how far it rose over the last day, nights and breaks included, so a week spent on its first night and quiet since does not read as running out. Advice, on the row it is about (or as a strip in the Detailed layout), and pace notifications say what to do about it — "Opus weekly is 91%. Sonnet is 34%. Switch models, not tools." — and the Usage Dashboard (⌘U) lays the week out in one window, in the panel's own colours and on its meters: the total first with the value line under it, each day's spend by assistant, with the day under the pointer named in a tip and any days you click pinned side by side under the chart, every limit with its pace tick, and where the money went by model and by project. The Cost card says what the spend is worth against the plan's published price ("$412 of API-equivalent value on the $200 Claude Max 20x plan · 2.1x"), and Share usage card… turns a range of it into a picture to post, labelled the estimate it is. With the optional hooks, the notch refreshes the moment a turn ends, counts your running sessions, and marks an assistant that is waiting for you. Before any hook is installed, the Sessions card still lists the sessions running in your terminals, each marked as found without it.

Everything, with the screenshots and every setting: docs/features.md. Energy, measured under a heavy Claude Code job on an M5 Pro with the panel solid, which is how it ships (a translucent material's blur is in the window only while the panel is open): 1.4 to 1.6 % of one core and a physical footprint of 63 MB; the method and the raw numbers are in docs/energy.md.

Install

• Download Notchmeter.dmg from the latest release and drag it to Applications. The DMG is Developer ID signed and notarised, and the app updates itself through Sparkle.
• Homebrew: brew tap Amir-Hackett/tap && brew trust --cask Amir-Hackett/tap/notchmeter && brew install --cask notchmeter. The middle step is Homebrew's, not this project's: it refuses to load a cask from a tap outside homebrew/cask until you say you trust it.

macOS 15 or later, Apple silicon or Intel. Notchmeter is free and stays free; if it earns its place in your notch, you can support the project.

Pre-release builds, building from source (scripts/build.sh) and what the first launch asks for: docs/install.md. Something not showing up: docs/troubleshooting.md.

Privacy and terms

Notchmeter is a read-only instrument. It never signs in anywhere, never refreshes or stores a token, and never makes an inference request. Each reading is borrowed from the tool that owns the account — the login Claude Code, Codex, Cursor, Gemini CLI, Copilot or Kimi Code already keeps on this Mac — and each token goes only to the vendor that issued it, over HTTPS, in the same read-only status request that vendor's own app or dashboard makes. There is no telemetry, no analytics, no crash reporting and no server of ours.

Every request names itself with a User-Agent: Notchmeter/<version> header, with two exceptions, because those two endpoints answer only the vendor's own client: the Copilot quota read and the Antigravity row's Code Assist calls are made under those clients' own identity. Each vendor's endpoint, what it is sent and how each request identifies itself is tabled in docs/accuracy.md, and if a vendor asks us to stop, that meter goes in the next release.

Three requests are not a meter's, all plain GETs of public data with no token, no usage figure and no system profile, and each with its own switch. Two go to GitHub: Sparkle's update check, once a day, fetching the release feed (Settings › General › Updates › Check for updates automatically), and since 0.9.0 the price catalog, once a day, fetching this repository's pricing/catalog.json so a model that launches between releases is priced at its published rate within a day (Settings › Appearance › Usage display › Update model prices from notchmeter's catalog; the Cost card names the prices it used). The third, off unless you turn it on, fetches the European Central Bank's daily euro reference rates once a weekday, so costs shown in another currency convert at the day's rate (Settings › Appearance › Usage display › Show costs in › Fetch today's rate) (docs/privacy.md).

Terms. Anthropic's are the most specific, so they are quoted rather than summarised. Claude Code's Legal and compliance page (read 2026-09-20): "Moreover, developers may not collect, store, or intermediate Claude.ai credentials or session tokens — sign-in to a Claude account must complete through Anthropic's own flow." The Consumer Terms of Service, section 3, item 7, forbids using the Services "Except when you are accessing our Services via an Anthropic API Key or where we otherwise explicitly permit it, to access the Services through automated or non-human means, whether through a bot, script, or otherwise." Notchmeter offers no login, routes nothing through the token and keeps no credential; every request to Anthropic names itself, and the usage endpoint is asked at most every five minutes, and while a session's status line is fresh only on Refresh, at a reset, and at most every 30 minutes for figures the status line does not carry. That poll is still a script making a request, and the app does not pretend otherwise: the channel Anthropic documents is the status line, and with Also poll Claude's usage endpoint off (Settings › Assistants › Claude Code) Notchmeter makes no request to Anthropic whatever. Whether to run it under your account is your decision.

The whole of it — every file read, every host and path asked, what is kept on disk, how often, and the full quotes with the app's reading of them — is in docs/privacy.md. The two optional macOS permissions are in docs/permissions.md.

Documentation

• docs/features.md: every meter, the screenshots, every setting, the command line and MCP server, the Claude Code plugin, the languages, and the advice and notification rules.
• Guides (sources in site/guides/): eight answers to the questions people ask, from why the cost estimate does not match the bill to every agent-notch app compared, each dated and stamped with the version it was checked against.
• docs/install.md: installing, testing a pre-release build, building from source, and the first launch.
• docs/privacy.md: what is read, where it is sent, what is kept, how often, and the vendors' terms.
• docs/accuracy.md: every rule behind the cost estimate, the primary sources, where it is known to differ from a bill, and why there is no rate-limit-header probe.
• docs/hooks.md: the optional hooks for Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI and Kimi Code, and the OpenCode plugin, what each sends and what each cannot report, how to install and remove them, and the status line.
• docs/permissions.md: Accessibility for Readouts › Auto and Mirror Cursor's cards, Automation for the jump to a terminal, and why local builds lose their grants.
• docs/energy.md: CPU and memory, measured, with the commands to reproduce them.
• docs/troubleshooting.md: what each message on a card means and what to do about it.

Contributing

See CONTRIBUTING.md. A security issue goes to SECURITY.md, not to a public issue; everyone taking part follows the Code of Conduct.

Credits

• The notch window is DynamicNotchKit 1.1.0 by Kai Azim (MIT), vendored in Vendor/DynamicNotchKit with its @Entry/#Preview macros replaced by plain code so it compiles without Xcode.
• Pace projection, reset copy, window naming and the cost rules follow OpenUsage (MIT), which in turn ports ccusage's transcript semantics. Feature set modelled on Codenotch and OpenUsage, reimplemented from scratch.

License

MIT, see LICENSE. DynamicNotchKit keeps its own MIT licence in Vendor/DynamicNotchKit/LICENSE.