vinzdg/codenotch

# Codenotch

A macOS app that pins a small black notch to a screen edge, showing how much of

each coding assistant's usage limit you have burned — and whether it is still

working, done, or waiting on you.

Hover a ring for its limit windows and when they reset. Claude's ring shows the

same current session window Claude Code's own /usage leads with, so the

two never disagree.

## What it reads

Codenotch never signs in anywhere. Every reading is borrowed from a credential

or session a tool on your Mac already holds — install and sign in to any of

them, and its ring appears. Switching a provider off in Settings stops its

credential being read at all and forgets the readings taken from it; it does

not sign you out of the tool that owns the account, and the row says so.

It also answers "is it still working?" — a thin arc spins inside a

provider's ring while a session is busy, and becomes a pulsing amber ring when

one is blocked waiting on you. Hover for every live session by name, where it

is running, and what it wants.

Two Claude Code logins are two rings. Anyone who keeps a work account apart with

CLAUDE_CONFIG_DIR=~/.claude-work claude gets a Claude (work) ring beside the

personal one, with its own limits, its own sessions and its own row in Settings.

Any ~/.claude- directory Claude Code has run against is found at launch;

the default ~/.claude always comes first, the rest in alphabetical order, so the

rings never swap places.

## Placement

The notch lives on any of the four screen edges. Right and left keep a

vertical column; top and bottom lay the readings out side by side. It pins

itself to the usable edge, so a bottom notch rests on the Dock and follows

when the Dock hides or moves. On a Mac with a hardware notch, the top

placement takes its exact shape, so the two read as one rather than as a bar

parked underneath it.

At rest it is a small pill on the screen edge that unfolds when the pointer

reaches it — configurable in Settings to always show, or to hide entirely.

Settings live in an orb below the notch: an arc at rest, a gear on hover.

The app itself can show a Dock icon, a menu bar icon, or neither.

## Updates

Codenotch updates itself. [Sparkle](https://sparkle-project.org) checks daily

and installs in the background without prompting; Settings says so and can

switch it off. Every update is EdDSA-signed, so nothing installs that wasn't

built and signed by the maintainer.

## Building

brew install xcodegen   # once
make run                # generate, build, launch a Debug build
make test               # unit tests

No signing identity is required for either. make release — which archives,

notarizes, and produces a signed auto-update feed — needs a Developer ID

certificate and an App Store Connect notary profile, and is only ever run by

the maintainer to cut an official release. See

[CONTRIBUTING.md](CONTRIBUTING.md).

Run with CODENOTCH_DEMO=1 to see fixed sample data instead of live readings.

## Architecture

Every provider implements UsageProvider (Sources/Providers/) and declares

its own Fidelity — .official, .derived, or .manual — so the UI never

presents a guess as if a vendor had published it. UsageStore

(Sources/Model/) polls them on a timer, keeps the last good reading across

launches, and degrades every failure to a visible status rather than a

made-up percentage.

The notch itself works in one-dimensional stack space (along/across)

regardless of which screen edge it's on; NotchPlacement is the only place

that maps that back onto real screen coordinates. NotchLayout holds every

measurement, quoted from docs/design/frame-124-hover-tooltip.png so the

layout can be checked against the design frame directly.