A finish notification lets you leave a long Claude Code run in the background. For the alert to help, it must arrive once, identify the session, and disappear when you have already replied. This guide uses Agent Island's released your-turn alert as the concrete implementation.
1. Install the current release
Download Agent Island v1.6.1 from the public GitHub release page. macOS users can also install it with brew install tristan666666/tap/agentisland. The current stable release contains macOS and Windows packages; live state and your-turn alerts are in the verified shared scope.
2. Allow notifications and keep turn alerts enabled
On macOS, the app requests notification permission. The foreground alarm window is the primary handoff surface, while the system banner remains useful when another app is active. Session details are optional: when enabled, the notification can include a thread label; when disabled, it only says that a background coding session finished a turn.
3. Start Claude Code and leave it running
Agent Island watches local Claude session activity. It does not submit a prompt, continue the run, or upload the transcript. While fresh assistant output is arriving, the Claude indicator remains in the working state. When a fresh terminal assistant event appears, the session can move to your turn.
4. Wait for a confirmed your-turn event
A completion event is held briefly before delivery. If a reply lands immediately, the newer local activity cancels the pending alert. This short confirmation step prevents an interruption for a turn the user has already resumed.
The delivery key includes provider, session, project, and turn identity. That lets the app suppress duplicate notifications for the same turn. Alerts acknowledged by the user are remembered for a bounded period, so a rescan does not replay the same handoff.
5. Use Open thread to return
The alarm includes provider, thread, and project context when details are enabled. The Open thread action attempts the most specific return path available.
For a Claude CLI session, Agent Island can resume the matching session in a terminal. Claude Desktop has a stricter boundary: its exact-conversation deep link is controlled by Claude, so the app may bring Claude Desktop forward and copy the session title for search instead of claiming a jump it cannot guarantee.
Why stale and false alerts happen
A local session can contain an old completion marker, receive a bookkeeping write after completion, or have newer activity from the user. A reliable alert system must compare those events instead of looking only at the final line or file modification time.
Agent Island does not alert for turns that were already complete before the app began observing them. A your-turn state also ages out. If the session leaves that state because the user replied or the evidence became stale, any pending task is cancelled and a visible alarm is dismissed.
If the notification does not match reality
Record the provider, approximate time, whether output was still arriving, and whether the alert was missing, late, duplicated, or attached to the wrong thread. Do not attach a full transcript, provider token, or credential to a public issue. The state transition matters more than the prompt content.
A finish notification cannot certify that the requested coding task is correct. It reports a local handoff: Claude ended a turn and the current evidence says a reply is needed.
For the underlying state model, read the Claude Code status monitor engineering guide.
← All posts