notch-limits
Website · Download for macOS · Releases
A tiny native macOS app that shows your Claude Code and OpenAI Codex usage limits around the MacBook notch. It covers the 5-hour session limit, the weekly limit and per-model limits, for as many accounts as you use.
The notch area becomes a Dynamic Island-style pill with one progress ring per account. Hover over it and it expands to show every rate-limit window, its percentage and when it resets. On Macs without a notch it falls back to a menu bar item.
If you juggle multiple Claude Code accounts (for example personal Max and a work Team plan via CLAUDE_CONFIG_DIR) and a ChatGPT/Codex plan, you can see at a glance which one still has quota left, without running /usage in each terminal.
Features
- Notch HUD: progress rings attached to the notch that expand on hover, like a Dynamic Island for your AI quotas.
- Menu bar fallback: the menu bar icon appears automatically when no screen has a notch (for example clamshell mode with an external monitor) or when notch mode is off. Clicking it opens the same black panel as the expanded notch, in light mode too.
- Claude Code limits: session (5h), weekly (all models) and weekly per-model limits (e.g. Opus/Fable), with exact reset times.
- Codex limits: primary and secondary rate-limit windows for ChatGPT plans (Plus, Pro, Team…).
- Multiple accounts: any number of Claude Code config dirs plus Codex homes, found automatically in
~/.claude* and ~/.codex* and managed in a Settings window.
- Colors only when needed: neutral gray rings, orange at 70% and red at 90%.
- Pace projection: each bar in the notch panel (and the menu bar panel) has a subtle tick where usage would be if spread evenly over the window, and "At this pace: limit today 16:20" appears under any window you are on track to hit before it resets. It is a linear projection from the current snapshot, with no stored history, and only shows once 15% of the window has passed.
- Best account now: with two or more accounts of the same provider, the expanded panel tags the one with the most headroom "Best now".
- Optional notifications: a heads-up when a limit reaches 90%, and another when a limit you hit resets ("Claude Work is available again"). Off by default; turn them on in Settings.
- Read-only and local: it reuses the credentials your CLIs already store. It never refreshes, rewrites or uploads tokens anywhere other than the official usage endpoint.
- Local-first: it reads the usage snapshots Claude Code and Codex already write to disk and only calls the API when they are more than 10 minutes old.
- Small and dependency-free: pure Swift + SwiftUI.
- Launch at login toggle built in.
- English, Português and Español: the UI follows your macOS language order and falls back to English.
Requirements
- macOS 14 Sonoma or later (the notch HUD needs a MacBook with a notch)
- Xcode Command Line Tools (
xcode-select --install)
- Logged in to Claude Code with a Claude subscription (Pro/Max/Team) and/or Codex CLI with ChatGPT sign-in
Install
One line (installs into ~/Applications, no Gatekeeper prompt):
curl -fsSL https://raw.githubusercontent.com/matheusm/notch-limits/main/install.sh | bash
Or download the app: grab NotchLimits.dmg (or the .zip), open it and drag Notch Limits to Applications. The app is not notarized yet, so on first launch open System Settings → Privacy & Security → Open Anyway.
Universal binary (Apple Silicon + Intel): a 3 MB DMG or a 1.7 MB zip.
Build from source
git clone https://github.com/matheusm/notch-limits.git
cd notch-limits
./build.sh # build, install to ~/Applications and launch
./build.sh --dist # universal NotchLimits.dmg + .zip in dist/
swift test # run the test suite
Contributing
Code must pass the same checks CI runs on every push and pull request:
brew install swiftlint
swiftlint lint --strict # strict style rules (.swiftlint.yml); any warning fails
swift build # compiler warnings are errors
swift test
The website in site/ deploys to notch-limits.vercel.app automatically on every push to main that changes it.
Configuration
Accounts are found automatically. At launch, and whenever you open Settings, the app looks at the folders directly inside your home folder:
| Account | Found when | Default name |
|---|
| Default Claude Code account | ~/.claude.json exists | Claude |
| Other Claude Code config dirs | a ~/.claude<suffix> folder contains a .claude.json file | Claude Work (for ~/.claude-work) |
| Codex | a ~/.codex or ~/.codex<suffix> folder contains an auth.json file | Codex, Codex Team (for ~/.codex-team) |
Discovery only checks that these files exist. It does not read them, your shell configuration or the Keychain. If nothing is found, the app shows the default Claude Code (~/.claude) and Codex (~/.codex) accounts with a hint to log in.
Settings
Open Settings with the gear button in the expanded notch or in the menu bar panel. The window uses the same black look as the notch panel. Clicking the gear in the notch collapses the notch so it never covers the window; it expands again once you move the pointer away from the notch and back.
Every account, found or configured, has a row where you can:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
