The short answer: notify once when a turn completes, persist when a session is blocked on the user, suppress repetition while the user is already working in an agent host, and make every alert open the exact session.
Completion and blockage are different events
A completed turn has produced a result. It deserves a clear signal, but repeating that signal indefinitely adds no information. A blocked turn is different: the agent cannot continue without a person. If that state disappears into Notification Center, parallel work quietly stalls.
The alert policy should reflect that difference. Completion can announce itself and remain visibly unread. A blocked session should stay visibly urgent until the provider reports a real transition.
What useful agent alerts should do
- Carry state. “Finished” and “needs your decision” should never look identical.
- Respect attention. If you are already typing in Claude Code, Codex or the terminal hosting another session, one pulse is enough to establish the fact.
- Remain legible after the animation. A persistent light is more useful than a notification banner you missed.
- Navigate precisely. Clicking should open the exact task or terminal tab, not leave you searching inside the app.
- Avoid inferred urgency. A long-running shell or subagent is context, not proof that the top-level session owns the turn.
Beacon's alert model
Beacon shows those states in a small corner-docked pill for every Claude Code and Codex session. When attention is needed, the same lights pulse over the current screen. You can snooze a flash briefly, but the underlying state does not lie: a blocked light remains red and a finished light remains green until the agent actually moves.
Why not rely only on native notifications?
Native macOS notifications are useful delivery, but they are chronological. Parallel coding work is spatial: you need the current state of all sessions, not a history of which banner arrived last. A stable status surface complements notifications by preserving the board after the banner is gone.
That stability also makes the system learnable. The fourth light is always the same session; only its color changes. Over time you recognize the work before reading a label.
Beacon's attention rules are local and configurable. Prompts, responses, code, project names, session names and paths are not included in its optional anonymous telemetry.