Get Notified When Codex Finishes a Turn

Verified 2026-08-05. Agent Island v1.7.1 exposes live Codex state and your-turn alerts on macOS and Windows. It reads local rollout events and does not upload the rollout content to Agent Island.

Codex can finish while its window is behind another task. Watching the terminal solves that problem by consuming your attention. A notification helps only when it can answer three narrower questions: did the current turn finish, is the event still fresh, and which session should open?

1. Install the current stable release

Download Agent Island from the public release page. The current stable release is v1.7.1 and includes macOS and Windows packages. Install the app, allow notifications on the operating system, and leave the Codex status indicator enabled.

2. Wait for a terminal Codex event

Codex rollout files contain structured events. A task start, turn start, user message, or user response means work is active. A task_complete or turn/completed event marks a finished turn.

task_started or user_message -> working
task_complete                -> your turn
newer turn start             -> working again
old completion               -> idle

The parser walks backward through complete JSONL records and ignores trailing metadata that cannot determine the turn. Silence is not a completion signal. It can mean a long tool call, a disconnected watcher, an abandoned session, or a process that has stopped writing for reasons unrelated to success.

3. Require fresh evidence

A completed turn remains actionable for a bounded window. Agent Island uses a 20-minute your-turn freshness limit. After that, the old event becomes idle instead of keeping an alarm active for the rest of the day.

Startup follows the same rule. A completion that happened before the monitor began observing the session is history, not a new interruption. If a newer user message or turn start appears, that newer evidence cancels the old completion state.

4. Deliver one alert per turn

The event key comes from stable identifiers such as the event ID, turn ID, item ID, or call ID. That key gives the reminder layer a precise deduplication boundary. A rescan may rediscover the same event, but it should not deliver the same alarm twice.

Child threads need separate handling. A completed child task does not necessarily mean the foreground Codex run needs the user. Agent Island keeps child-thread notification noise out of the main provider state unless the current reminder settings explicitly allow it.

5. Return to the matching Codex session

The notification retains local provider and session identity. The return button then attempts the most specific Codex route available on that machine. The route is a convenience, not remote control: Agent Island does not submit the next prompt or restart the run.

A return target can become unavailable when the host application closes, removes history, or changes its navigation contract. The status remains useful even when a historical deep link cannot be reopened.

When a notification looks wrong

Check the event order before changing the alert settings. A duplicate usually points to an unstable event key. A stale alarm points to missing freshness or newer-turn suppression. A missing alarm may mean the last complete JSONL record never reached a terminal event.

When filing an issue, include the operating system, Agent Island version, Codex version, approximate time, and whether the problem was missing, late, duplicated, or attached to the wrong session. Do not post the full rollout, credentials, or provider tokens.

What the notification proves

The notification proves only that the latest fresh local evidence marks a finished Codex turn. It does not certify the code, tests, deployment, or requested outcome. Agent Island reports the handoff; the user still reviews the work.