Codenotch shows coding agent usage limits on the Mac screen edge

Codenotch is a macOS app that shows how much of each coding agent's session limit you have used, in a small black notch pinned to the edge of the screen. It reads Claude Code, Cursor and Codex. The repository was created on 5 September 2026 and had 196 stars and 31 forks when the GitHub API was checked the same day.

The readings refresh every 60 seconds. Hovering a provider opens the individual limit windows and when each one resets. The ring shows the current session, which the author says is the same window Claude's own usage panel shows first, so the two do not disagree. Inside the Claude ring a thin arc spins while a session is working and turns into a pulsing amber ring when a session is blocked waiting on you.

Three levels of confidence, labelled

The interesting part is what the project admits it cannot do. The README states plainly that no LLM vendor publishes a clean "your session limit is N percent used" API. So each provider adapter declares its own accuracy level as official, derived or manual, and the interface never presents a derived number as though it were official.

Claude is the official case. The app reads the OAuth token that Claude Code keeps in the login keychain and calls the same endpoint Claude's own usage screen uses. The author is direct that this is not a published API and can change without notice, so the response format is checked by tests, and any failure shows a visible stale, needsAuth or error state rather than a made-up percentage. Cursor and Codex read locally instead: Cursor from the editor's own SQLite state store, Codex from the rate-limit snapshots it writes into its rollout logs. Neither needs a credential or a network call. Perplexity has an adapter that is kept but not registered.

The local session files under ~/.claude/projects were the original plan and became the fallback. They hold token counts but no limits and no window metadata, so a percentage from them would need an invented denominator.

What it costs to adopt

It needs macOS 26 and is written in Swift 6 with SwiftUI and AppKit. The app has to be signed with a Developer ID identity for the one-time keychain grant to stay valid after rebuilds, and an unsigned build re-prompts every time. The repository carries no licence file, which matters for anyone whose employer requires one. The author also labels the name itself as a working title.

The polling is careful in a way worth copying. The endpoint answers 429 when it receives too many requests, and returns Retry-After: 0 when it does. Codenotch uses that hint only to raise the minimum wait, never to lower it. It starts with a 60 second wait, doubles it on each consecutive 429, and stops at 15 minutes. It keeps the last good reading across launches so a refused fetch shows dated numbers with a dimmed ring rather than nothing, and it saves the end time of the wait so relaunching during a wait period waits instead of spending an attempt.

Anyone paying for two or three coding agents is already guessing at the same question several times a day: is there enough budget left in this window to start a long run. Getting that wrong costs a half-finished refactor and a wait. The wider point is the honesty about accuracy. A number scraped from an unpublished endpoint and a number derived from local token counts are not equally trustworthy, and most usage dashboards show both in the same typeface. Labelling which is which is the part to copy, whether or not you install this app.

Source

vinzdg/codenotch, GitHub, created 5 September 2026.