A coding agent finishes a turn. The monitor schedules an alert. Two seconds later, the developer has already replied.
Should the notification still appear?
If completion is stored as a boolean, the answer is usually yes. The alert was scheduled from a true value, and the delayed task has no reason to question it. The result is a technically accurate notification that is already obsolete.
We found it more useful to model a completion as a short-lived lease on human attention. The lease has an identity, a freshness boundary, and a condition that can disappear before or after delivery.
Detection is not permission to interrupt
The local session scanner and the reminder system answer different questions.
The scanner asks whether the latest meaningful evidence says the agent ended a turn. The reminder system asks whether this is a new handoff that still needs the user.
That separation matters at startup. A completed transcript may be correct status information, but it is not necessarily new information. Replaying every completion found on disk when the app opens would turn accurate history into noisy alerts.
Agent Island therefore baselines completed turns it discovers at startup. They can appear in the status surface without being treated as newly created interruptions.
Re-check state at delivery time
Local session files change quickly around a handoff. A user can return to the terminal before a notification delay expires. A client can also append bookkeeping data after the assistant's terminal event.
The reminder is scheduled with a short delay, then validates the current state again:
alerts enabled
+ same turn still needs attention
+ turn has not been acknowledged
+ turn has not already been delivered
= show the alert
The second check is the important part. A delayed task should not trust the snapshot that created it.
This pattern applies beyond coding agents. Any notification based on a reversible condition should verify that condition immediately before interrupting the user.
Give the handoff a stable identity
Deduplicating on provider name is too broad. One Claude session can finish several turns. Deduplicating on the latest file timestamp is too narrow because the same turn can be observed through repeated scans.
The delivery key needs enough context to identify the handoff: provider, session, project, transcript, and turn identity. Repeated observations of that key are one event. A later turn gets a different key even when it belongs to the same session.
Delivered and acknowledged keys are retained for a bounded period. That prevents a refresh from replaying an old alert without turning the reminder layer into a permanent transcript database.
Cancellation has to work after delivery too
Preventing an alert before it appears solves only half of the stale-state problem.
The user may reply from another window while the notification panel is already visible. On each scan, the reminder layer compares the current attention keys with the previous set. When a key disappears, it cancels the pending task and dismisses the corresponding visible alert.
The UI follows the source condition instead of asking the user to close evidence that is no longer true.
Bursts are one human event more often than many
Agent workflows can finish several child sessions within seconds. The filesystem sees multiple completions. The person supervising the run may see one parent workflow reaching a handoff.
Delivering every child completion optimizes for event count, not attention. The reminder layer selects the newest relevant turn and baselines the rest of the burst. Subagent alerts remain opt-in because child-session traffic can otherwise dominate the signal from the main session.
The return action must be honest
A useful alert identifies the provider, project, and session. Its action should return the developer to that work.
For a Claude CLI session, a known session ID can be resumed in a terminal. Claude Desktop does not expose the same exact-conversation routing contract. In that case, activating the app and copying the session title for search is more honest than labeling an imprecise action as a guaranteed deep link.
Platform limits belong in the interaction design, not in a footnote after the button fails.
What the signal does not prove
"Your turn" means the local evidence says an agent ended a turn and a response is still needed. It does not mean the generated code is correct, the task is complete, or the output is safe to merge.
That boundary keeps the alert useful. The monitor owns attention state; the developer still owns verification.
The full setup and behavior guide is here: Get notified when Claude Code finishes.
Agent Island is open source for macOS and Windows: source and releases.
Top comments (0)