Codenotch: a macOS notch that shows your coding assistant usage limits
A macOS app that pins usage limits from Claude Code, Cursor, Codex, and Antigravity to a screen edge.
At a glance
- What is it?
- Codenotch pins a small black notch to a screen edge and reports how much of each coding assistant's usage limit you have burned. It is a macOS app written in Swift, with a Rust/Tauri 2 port for Windows.
- Who is it for?
- Adopt Codenotch if you run several assistants on one Mac and want their limit windows visible without opening each tool. Skip it if you work on a single provider whose own /usage already answers the question, or if you need a signed, notarized build for a fleet deployment: the preview and per-commit disk images are ad-hoc signed, and the Windows installer is not code-signed at all.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Swift, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 16, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What problem the notch actually solves
Coding assistants meter you. Claude Code has a current session window, Codex has a 5-hour and a weekly limit, Kiro counts monthly credits, Kimi tracks a 5-hour rate window plus a weekly quota. Each of those numbers lives behind a command or a settings screen in the tool that owns it. If you switch between four assistants in a day, checking each one is a context switch you pay for every time.
Codenotch's answer is a small black notch pinned to a screen edge. It shows a ring per provider, and hovering a ring reveals its limit windows and when they reset. The README describes the collapsed state as showing how much of each assistant's usage limit you have burned and whether the tool is still working, done, or waiting on you. That third state matters more than the percentages: a session that is waiting on you is not burning quota, and a glance at the edge of the screen tells you so without a terminal.
The intended user is someone running several of these tools on one Mac, not a team dashboard and not a billing system. There is no aggregation across machines and no history beyond what the providers themselves return.
How the rings get their numbers
The design principle in the provider table is borrowing. Most entries do not ask you to sign in to Codenotch at all. They read a credential or session that a tool already stored on your Mac, then call the same endpoint that tool's own usage command calls.
Grok is the clearest example: Codenotch reads the Grok CLI session in ~/.grok/auth.json and queries the same credits billing endpoint /usage uses. Kimi reads ~/.kimi-code/credentials/kimi-code.json and asks the same /usages endpoint the CLI's /usage asks. Command Code uses the key the app writes to ~/.commandcode/auth.json. GitHub Copilot authenticates with the GitHub CLI session already on the Mac, which the README specifies as gh auth login. Codex uses the local Codex sign-in. Cursor reads the editor's signed-in session from its local SQLite state, or the cursor-agent login in the keychain.
Claude Code has a fallback chain rather than a single source. The README lists, in order: Claude Desktop's own cached usage response where Desktop is running and signed into the same account; then Claude Code's own /usage, asked of the installed claude binary; then the OAuth token in the login keychain against the endpoint that command uses. The README also claims the Claude ring shows the same current session window that Claude Code's /usage leads with, so the two never disagree.
Two providers break the borrowing pattern. DeepSeek and MiniMax use explicit sign-in inside Codenotch's own WKWebView. The README is explicit that DeepSeek never reads a browser's cookies or credentials and only makes requests after you choose Sign in to DeepSeek from Codenotch. Antigravity is a third case: it tries Antigravity's local language server first, then Google's quota endpoint, and falls back to a plain request count when neither will answer for the account. A request count is not a quota percentage, and the table says so.
Installing Codenotch and reading your first ring
The README points at a disk image whose asset name is stable across releases, so the download link resolves to the newest build without being updated. The app is described as signed, notarized, and self-updating from then on. The download section says macOS 15 or later, while the platform badge at the top says macOS 26+. Those two statements do not agree, and the README does not reconcile them, so check your own version against both.
If you want unreleased main without an Xcode install, the preview build is rebuilt from every commit. Neither the preview nor the per-commit disk images are notarized. The README says they are ad-hoc signed because the Developer ID certificate exists on one machine, so macOS quarantines the download. After dragging the app to Applications, clear the flag once:
xattr -dr com.apple.quarantine /Applications/Codenotch.appIf macOS reports the app as damaged, the README attributes that to the quarantine flag rather than a bad download, and points back at the same command.
Building from source goes through the Makefile at the repository root, which sets DEVELOPER_DIR to /Applications/Xcode.app/Contents/Developer only when that path exists and the caller has not already chosen a toolchain. The comment explains why: exporting a path that is not there breaks every target with xcrun: missing DEVELOPER_DIR on a machine that only has Command Line Tools. The Makefile derives ARCH from uname -m and DEST from platform=macOS,arch=$(ARCH). CONTRIBUTING.md is cited as the source for building without an Apple account.
For the Windows port, the installer is named Codenotch-Setup.exe in every release, installs for the current user without administrator rights, and fetches WebView2 if Windows does not already have it. It is not code-signed, so the first run triggers SmartScreen, where the README says to choose More info and then Run anyway.
Pairing a phone, and the local-network boundary
The phone link is the part of Codenotch with a documented protocol. The iOS and Android app shows the same usage percentages, reset times and session states as the notch. The README states it reads only what the notch already displays, never tokens, credentials or raw API responses.
Pairing starts on the Mac under Settings › Phone › Connect a Phone, or the menu item. A QR code appears with a five-minute countdown. You scan it with the phone app or copy the link and paste it in. The Mac and phone must be on the same Wi-Fi network. The server answers only local-network addresses and rejects anything routed over the internet. Each code is single-use and expires after five minutes, and reopening the window mints a fresh one.
Removal is a single action: Settings › Phone, find the device, click Remove. The README says its credentials are deleted immediately and any subsequent request from that phone is rejected. The wire-level details live in docs/phone-link-protocol.md, and the repository root also carries PHONE-LINK-V3.md and phone-link-v3-vectors.json, which suggests the protocol is versioned and has test vectors.
Where Codenotch is the wrong tool
The failure mode is credential drift. Nearly every provider row depends on a file or a session that another application owns. If you sign out of the Grok CLI, rotate the Kimi Code CLI session, or run gh auth logout, the corresponding ring loses its source. The README does not document what the notch shows when a credential disappears, and it does not document rollback for a bad release either. The app updates itself from then on, which is convenient until an update misreads a provider, at which point the documented recovery is not in the README.
Antigravity is a softer limitation. When neither the local language server nor Google's quota endpoint answers, the README says Codenotch falls back to a plain count. A count tells you how many requests you made, not how close you are to a cap, so the ring is showing a different quantity than the other rings. Treating them as comparable is a mistake.
DeepSeek and MiniMax need an explicit sign-in inside Codenotch's WKWebView, which is a second place to authenticate and a second session to keep alive. That is a deliberate privacy trade: the README says DeepSeek never reads a browser's cookies or credentials. The cost is that it is not zero-configuration like the borrowed-credential providers.
Finally, this is a desktop indicator, not a control plane. There is no documented way to set a budget, cap a session, or alert a team. If your problem is spend governance rather than personal awareness, the notch is looking at the wrong layer.
Alternatives and how they differ in approach
The honest alternative for a single provider is the provider's own command. Claude Code has /usage, and the README states the Claude ring deliberately mirrors the current session window that command leads with. Kimi's CLI has /usage against the same /usages endpoint Codenotch reads. Kiro's kiro-cli prints the same /usage that Codenotch queries for monthly credits. If you only use one assistant, running its own usage command gives you the same number with no extra process, no keychain access and no quarantine flag to clear.
What that alternative cannot do is put several providers in one glance. The difference is aggregation and persistence, not data: Codenotch is not computing anything the CLIs do not already compute. It is reading their sessions and drawing rings. That is also why it breaks when the sessions break.
For local models the comparison is different. The README lists Ollama and LM Studio as local runtime sources, with LM Studio reporting loaded models, what each is doing from its SDK socket, and speed, context use and tokens per day from its server log. LM Studio's own interface already shows loaded models and activity. Codenotch's contribution there is putting that next to remote quota rings, not replacing the tool's own panel. The README notes no relay is needed for LM Studio.
Maintenance, licence and upgrade cost
The repository is not archived and the last push was on 2026-09-16. Release v1.12.0 is tagged the same day, v1.11.0 three days earlier, and a preview build a week before that. That cadence means the provider table is a moving target: endpoints and credential file paths change when the upstream tools change them, and each of those changes is a potential ring outage until the next release. Budget for that if you depend on a specific provider.
The licence is MIT, as stated in the repository and shown in the README badge. MIT permits use, modification and redistribution with the licence and copyright notice retained. What it does not do is grant you anything from the upstream providers whose endpoints Codenotch calls. Reading a session file that another application wrote, and querying that application's usage endpoint with its credential, is governed by that provider's terms, not by Codenotch's MIT grant. The README does not discuss those terms, and this is not legal advice; if you are deploying this in a company, that question is worth asking before you roll it out.
The Windows port adds a second maintenance surface. It is Rust/Tauri 2 with the same design and providers, living in windows/, and the README says every Windows change leaves an installer on its Windows Package run. Two ports mean two sets of provider integrations to keep aligned, and the README does not describe how that alignment is enforced.
Editorial conclusion
Adopt Codenotch if you run several assistants on one Mac and want their limit windows visible without opening each tool. Skip it if you work on a single provider whose own /usage already answers the question, or if you need a signed, notarized build for a fleet deployment: the preview and per-commit disk images are ad-hoc signed, and the Windows installer is not code-signed at all. Before adopting, verify two things on your own machine. First, that the credential path for your provider actually exists, for example ~/.grok/auth.json for Grok or a gh auth login session for GitHub Copilot. Second, whether your macOS version satisfies the README's platform badge, since the download section says macOS 15 or later while the badge says macOS 26+.
Frequently asked questions
Does Codenotch read my API keys or tokens?
For most providers it borrows a credential or session that another tool already stored on your Mac, such as ~/.grok/auth.json for Grok or the GitHub CLI session for Copilot, and uses it to call that tool's own usage endpoint. The README states the phone app reads only what the notch already displays, never tokens, credentials or raw API responses, and that DeepSeek never reads a browser's cookies or credentials.
Which coding assistants does Codenotch support?
The README's provider table lists Claude Code, Cursor, Codex, DeepSeek Platform, Antigravity, GLM, MiniMax, Ollama, LM Studio, Grok, OpenCode, Command Code, GitHub Copilot, Kimi and Kiro. Sources are marked official, derived from official responses, or local runtime depending on the provider.
How do I install Codenotch on macOS?
Download the disk image from the releases link; the README says the asset is named Codenotch.dmg in every release and is signed, notarized and self-updating. The download section states macOS 15 or later while the platform badge says macOS 26+, so check both against your machine.
Why does macOS say the Codenotch preview build is damaged?
The README attributes that message to the quarantine flag rather than a bad download, because the preview and per-commit disk images are ad-hoc signed rather than notarized. It gives one command to clear it after dragging the app to Applications: xattr -dr com.apple.quarantine /Applications/Codenotch.app.
Community notes