Getting told when Claude Code needs you
A long turn ends while you are somewhere else. What tells you depends on where you are looking.
What Claude Code does on its own
Claude Code can raise a notification itself, and which channel it uses is a setting — the terminal bell is one of them. That works when the terminal is on screen or in earshot.
It reaches you in the window that ran the turn. With several agents running in several tabs, that is the limitation rather than the feature.
What Agent HUD shows on the Mac
The island is the alert. When a turn finishes it shows the session title and how long the turn took, then settles back; nothing lands in Notification Centre, because Agent HUD does not post macOS notifications at all.
Quota events use the same place: a warning when a window is running low, a reminder when one resets, and the glow's colour carrying the state in between.
What raises one, and what does not
- Four quota events notify once each: crossing 90% used, reaching zero, a forecast that the window will run out before its reset, and a confirmed reset.
- The first reading of a window after launch is a silent baseline, so whatever is already on screen when you start never alerts.
- A reading older than 30 minutes stays visible but stops raising anything.
- Nothing is raised while collection is paused or the last refresh failed, and an alert that arrives while the glow is hidden is dropped rather than queued.
Away from the Mac
Agent HUD Remote syncs one Mac's activity to the free iPhone, widget and Apple Watch apps, where the same events arrive as real system notifications and running sessions appear as a Live Activity.
That is the part the terminal cannot do: the turn finishes while you are in another room, and your wrist says so.
Common questions
- Does Agent HUD put anything in Notification Centre on the Mac?
- No. On the Mac every alert is the island itself. System notifications only happen on iPhone and Apple Watch, through Agent HUD Remote.
- Why did I not get an alert for a window that is already at 95%?
- The first reading of a window after launch is a baseline rather than an event. Crossing the threshold while Agent HUD is running is what raises the alert.
- Will it alert twice for the same thing?
- No. Each of the four events notifies once for that window, so a window sitting above 90% does not repeat.
- Do I have to configure anything?
- No. Agent HUD reads the sessions already on your Mac, so turn completion appears without hooks, keys or setup.
Guides
Last updated: 2026-09-20 · The behaviour described here is documented in full, with the code it comes from, in Agent HUD Open. github.com/jazzenchen/agent-hud-open