Codenotch

A macOS app with no window and no Dock icon: its whole surface is a small black notch welded to one screen edge, answering one question at a glance — how much of each coding assistant’s usage limit has already been spent. Claude Code, Cursor, Codex, Antigravity and about a dozen further providers each get a ring; hovering one lists its limit windows, when each resets, and every live session by name, with a thin arc inside the ring while an agent is working and an amber pulse when one is waiting on you. The five-hour limits can also be drawn into the menu bar as text, the last good reading survives a relaunch, and the same percentages go to a phone app over the local network. Underneath, one admission holds the design up: no vendor publishes a clean session-limit API, so every adapter declares its own fidelity, borrows what the owning tool already keeps, and turns each failure into a visible status rather than an invented percentage.

Who built itThe repository’s owner, under the account vinzdg: 387 of its 791 commits, all written in the 25 days between 2026-09-05 and 2026-09-30. The other 404 are spread over the forty-nine further accounts the contributor list names, led by RawJat on 58 and mulhamna on 57. 103 commits carry a co-author trailer, 88 of them naming a Claude model, with Codex on 4 and Cursor on 2.

1. 01

   Twenty-five days, nineteen releases, and one renamed app

   The repository was created on 2026-09-05 and by 2026-09-30 had 791 commits, 2,639 stars, 420 forks and 19 releases — v1.4.0 on 2026-09-06 through v1.20.0 on 2026-09-30, plus a rolling preview tag that is rebuilt and re-uploaded on every push to main. The app ships its own release-note catalogue going back to 1.0.0, so the version line predates its first GitHub release, and the design spec still opens by calling the name a working one rather than a decision. The rename from UsageNotch left traces the author wrote down: the old app is still installed at /Applications/UsageNotch.app and nothing removes it, the keychain asks again because its access list is keyed on a designated requirement containing the bundle identifier, and the Sparkle feed still points at vinzdg.github.io/usage-notch/ while the disk image is served from hivinz.com.

2. 02

   Claude Code and Cursor: the keychain, the cache, and the editor’s own database

   The design document opens with the admission the project is built on: no vendor publishes a clean "your session limit is N% used" API. So each adapter borrows what the owning tool already holds, declares its own fidelity — official, derived or manual — and the tooltip prefixes anything computed here with a tilde. Claude Code has three sources in order. Claude Desktop is a Chromium app, so the usage response its own panel draws sits in an HTTP cache under ~/Library/Application Support/Claude; only entries whose cached URL is this account’s /api/organizations/<id>/usage are opened, matched on the organisation Claude Code records for the profile, and because the bodies are zstd a decode-only build of Zstandard is vendored under Sources/Vendor/zstd. Then claude "/usage" is run. Then the OAuth token in the login keychain is sent to GET https://api.anthropic.com/api/oauth/usage, the same endpoint that command uses, which returns Anthropic’s own session and weekly figures. Cursor’s documented Admin and Analytics APIs are team-scoped and need an admin key, so the ring asks GET https://cursor.com/api/usage-summary with the editor’s own session read out of state.vscdb — cursorAuth/accessToken and cursorAuth/stripeMembershipAuthId — sent as the cookie WorkosCursorSessionToken=<account>::<token>, because a bearer header on the same token answers 401.

3. 03

   Codex and Antigravity: a token off disk, and a language server on loopback

   Codex is read live from GET https://chatgpt.com/backend-api/wham/usage, authenticated with the access token and account id the Codex CLI keeps in ~/.codex/auth.json, which this app reads and never refreshes or writes. When that fails it falls back to the rate-limit snapshots Codex writes into the rollout log of each thread, the newest found through the threads table of state_5.sqlite rather than by walking a sessions tree of thousands of files. Antigravity is the interesting one, because Google refuses: the quota RPC on cloudcode-pa answers 403, "You do not have a valid license of this product", for a personal account, because the API judges which client is asking. Antigravity’s own window has the same problem and solves it the same way, so this app does too — it finds the language server’s pid in the process table, reads the --csrf_token off its command line, finds the ports it listens on with lsof, and POSTs {"forceRefresh":true} to /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary on loopback, with the header the binary turned out to want, x-codeium-csrf-token.

4. 04

   How often it asks, and what happens when it is told to stop

   UsageStore ticks every 15 seconds and refreshes a busy provider every 30, dropping to five minutes when nothing is running, because usage cannot move while nothing is using it. Three events ask outside that schedule — a session stopping, the menu bar item being opened, and the pointer landing on a ring — and the last is spaced so that four rings hovered in four seconds cost one fetch. Anthropic’s endpoint answers 429 with Retry-After: 0, which obeyed literally meant waiting zero seconds and firing straight back into the limit; the hint may now only raise a floor that starts at 60 seconds, doubles per consecutive 429 and caps at 15 minutes, and the deadline is persisted so that relaunching during a penalty waits instead of spending an attempt. The author’s note on that is blunt: a development loop of make run was the thing sustaining its own punishment. A 429 renders as staleness rather than as an error, and a remembered reading is never presented as a live one — it comes back dimmed and dated.

5. 05

   The bugs the author wrote down, including one he got wrong

   The code comments and the task history keep the failures that cost a day each. Opening Cursor’s or Codex’s SQLite store with immutable=1 ignores the write-ahead log, so a live agent looks idle and a rotated token looks current — and after a restart, with the -shm sidecar gone, a read-only open fails outright, which is how the app came to report no Codex threads on a machine that had 2,752 of them. Claude’s session file writes procStart as a ctime string in UTC, so parsing it as local time put the pid-reuse guard seven hours out and the activity indicator silently never appeared. The ring’s headline used to be the first window in the array, and Claude drops five_hour the moment that window rolls over, so at exactly the moment someone was watching, the weekly figure slid into the session’s place; the headline is now named rather than positional and shows a dash when the named window is gone. On the disk image issue, the same commenter who had blamed a stale download published a correction — "I was wrong about the cause" — followed by a third state his own rebuild produced, three times out of three.

6. 06

   A macOS app, a Rust port, and fifty accounts

   The contributor list names fifty accounts, with the author on 387 commits and the next two on 58 and 57. The Windows port is not a port of the code: windows/ is a separate Rust and Tauri 2 application that reimplements every provider against the same wire formats, with its own i18n file, its own installer and its own packaging workflow — and the three pull requests that carry the notch round a Windows screen border all land there. The queue around it is a mix of ports and arguments. One contributor spent three pull requests on whether the menu bar item should reserve width, and settled it with counts rather than taste — five reflows per five-hour window for one provider, about one an hour — by reversing his own earlier position in the last of them. Another filled in the Chinese strings that release still showed in English, with Traditional Chinese keeping Taiwan wording. A third found that a Custom Endpoint reached over a Tailscale address failed on App Transport Security and added an exception scoped to 100.64.0.0/10. Fifty-four issues were open at the end of the month. An agent app has no window to print into either, so failures go to the unified log, and the author records that the first attempts at a diagnosis were guesses made from screenshots.