# notch-agent-hud

> A macOS notch overlay showing Claude Code and Codex sessions and usage

- Repository: https://github.com/thilinaa/notch-agent-hud
- Category: Coding agents & dev tools
- Stars: 11 · Forks: 1 · Language: Swift · License: MIT
- Experience: Beginner friendly
- Page: https://ir.adyog.com/repos/thilinaa/notch-agent-hud/

When you run several coding agents in different terminal tabs, it is easy to miss that one is waiting for you, or to hit a usage limit without warning. NotchHUD puts that information in a pill at the top of the screen, such as '2 working · 1 needs you'. Click it to expand a panel with each session and your usage.

Claude Code sessions report through hooks that setup adds to ~/.claude/settings.json, which send events to a local server on your Mac. Codex sessions are detected by watching its session files. Usage numbers come from Anthropic's and OpenAI's usage endpoints, using tokens the tools already store. You can switch that off to get estimates only.

It also puts a pace mark on each usage meter, sends notifications as you near a limit, and can run a scheduled 'hi' to Claude so your 5-hour window is already running when you sit down. It warns when your active gh account does not match the rules you set for a repository. The README says nothing leaves your Mac except the usage calls and an update check.

## What it does

- **Session status at the notch**: A pill shows how many agents are working and how many need you. The expanded panel lists sessions that need you first, and clicking a row jumps to the terminal tab (Ghostty is matched by working directory).
- **Usage per subscription**: Shows 5-hour and weekly windows for each Claude account and for Codex, as bars or rings, used or remaining. A pace tick shows how far the window has run, and a line says when you will hit the limit if quota is going faster than time.
- **Alerts**: Notification Center messages fire when a window crosses a threshold you choose (50 to 90%), hits its limit, or resets.
- **Window warm-up**: An optional schedule runs 'claude -p hi' at set times so the first 5-hour window has already started. It skips if a window is running, and each run costs one short message.
- **GitHub account guard**: Reads the active gh account and warns when it does not match the account your folder or owner rules expect, with a one-click Switch.

## What you could build

- Keep an eye on several Claude Code and Codex sessions without switching terminal tabs.
- Track how fast you are using each subscription's 5-hour and weekly quota.
- Get a notification before you hit a usage limit mid-task.
- Start your 5-hour Claude window before you sit down to work.
- Avoid committing to a repository with the wrong GitHub account when you have work and personal logins.

## Who it's for

Mac users who run Claude Code or Codex daily, often with more than one account; you need macOS 14 or newer and should be comfortable with an app editing your Claude Code hook settings.

## Get started

Download the latest .dmg from the Releases page, drag NotchHUD to Applications and launch it. The setup window installs the Claude Code hooks, names your subscriptions and asks for the Accessibility permission needed for terminal-tab focus.



Tags: claude-code, codex, macos, menubar, usage-tracking