Codenotch puts your Claude, Cursor and Codex usage limits on the edge of the screen

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 leads with, 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 fidelity 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 shape is pinned 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 survive 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 hit too hard, and returns Retry-After: 0 when it does. Codenotch treats that hint as a floor-raiser only, backing off from 60 seconds, doubling on each consecutive 429, capped 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 persists the back-off deadline so relaunching during a penalty 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 fidelity. 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 take, whether or not you install this app.

Source

vinzdg/codenotch, GitHub, created 5 September 2026.