Should I still write a notify program?

If you want something specific to happen — a webhook, a light, a message to a channel — yes, that is what it is for. For knowing a turn finished, the island already does it without a script.

Does Agent HUD need the hook to be installed?

Not for Codex. It reads the rollout logs Codex already writes, so completions appear without configuring anything.

Do Desktop and the CLI both show up?

Yes. On one Codex home they share an account, so their sessions and windows appear together rather than twice.

Will Agent HUD post a macOS notification?

No. On the Mac every alert is the island. System notifications happen on iPhone and Apple Watch, through Agent HUD Remote.

Agent HUD · Guides

Getting told when Codex finishes a turn

Codex will tell something when a turn ends. What it tells is up to you.

What Codex does on its own

Codex can hand a completed turn to a program you name, and it has a lifecycle hook that runs right before it ends a turn. Between them you can make almost anything happen when work finishes.

The cost is that you write it. A script, a notifier, a sound — and then again for each machine you work on, and again when the shape of the event changes.

What Agent HUD shows on the Mac

The island is the alert, with no configuration at all. A finished turn shows the session title and how long it took, then settles back. Nothing lands in Notification Centre, because Agent HUD does not post macOS notifications.

It watches the rollout logs Codex already writes, so Desktop and the CLI both appear, and a session counts once even after it is archived.

Quota events, in the same place

Four things 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 what is already on screen at start-up never alerts.
A reading older than 30 minutes stays visible but raises nothing.
Nothing is raised while collection is paused or the last refresh failed.

Away from the Mac

Agent HUD Remote syncs one Mac's activity to the free iPhone, widget and Apple Watch apps. There the same events arrive as real system notifications, and running sessions appear as a Live Activity with the count still going.

Common questions

Should I still write a notify program?: If you want something specific to happen — a webhook, a light, a message to a channel — yes, that is what it is for. For knowing a turn finished, the island already does it without a script.
Does Agent HUD need the hook to be installed?: Not for Codex. It reads the rollout logs Codex already writes, so completions appear without configuring anything.
Do Desktop and the CLI both show up?: Yes. On one Codex home they share an account, so their sessions and windows appear together rather than twice.
Will Agent HUD post a macOS notification?: No. On the Mac every alert is the island. System notifications happen on iPhone and Apple Watch, through Agent HUD Remote.

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