Codex Status Monitor: Local State and Your-Turn Alerts

Verified 2026-08-03. Agent Island v1.7.1 monitors Codex session state on macOS and Windows. The shared released scope is live state and your-turn alerts. The monitor does not upload rollout content to Agent Island.

A file timestamp is not enough to tell whether Codex is working. Rollout files contain task starts, user messages, completed turns, tool results, and metadata. A status monitor has to identify the latest meaningful event, preserve its order, and let old evidence expire.

Read semantic events, not just modified time

Codex records structured JSONL events under the local Codex data directory. In the current state parser, a new task start or user message means the session is active. A task_complete or turn/completed event means the latest turn finished. The parser walks backward so trailing tool or metadata records do not hide the event that determines the turn.

task start or user message  -> working
task complete               -> your turn
fresh activity, no terminal event -> working
old evidence                -> idle

This is also why a monitor should not infer completion from silence. No new write might mean a finished turn, a long-running process, a disconnected watcher, or an abandoned session. A completion state needs a completion event.

Expire completed turns

A terminal event should not keep a red badge on screen forever. Agent Island caps the actionable your-turn window at 20 minutes. A completed turn inside that window can request attention; older evidence returns to idle. The exact window is an implementation boundary, not proof that the coding task itself succeeded.

Startup needs the same restraint. If the app discovers a turn that ended before monitoring began, that event is historical context. The reminder layer tracks event identity so reconnecting or rescanning the same record does not create a second alert.

Keep child-thread noise out of the main signal

Codex can spawn child threads that finish while the parent run continues. Treating every child completion as a foreground alarm makes the monitor unusable. Agent Island keeps child-thread notifications off by default and ranks the current provider state separately from reminder delivery.

For multiple active sessions, the indicator chooses the most urgent fresh state. An unacknowledged your-turn event outranks ordinary work, while authentication and rate-limit states remain separate because they require a different response.

Return to the right session

A notification is only useful when it retains enough local identity to route the user back to the relevant session. Agent Island stores a local thread key derived from stable event or session identifiers, then associates the reminder with the matching Codex context. The interface can offer a return action without sending the transcript through an Agent Island server.

The monitor cannot guarantee that another app will preserve every historical navigation target forever. A return action is a convenience attached to observed local identity, not a remote session-control protocol.

What the status cannot prove

Working means recent session evidence is moving. Your turn means the latest fresh turn reached a terminal event. Stalled means previously working evidence went quiet inside an attention window. None of those states verifies tests, code quality, deployment, or product completion.

Codex no longer exposes the old five-hour quota model used by earlier builds, so this page makes no Codex five-hour quota or auto-resume claim. Usage and reporting surfaces also have platform-specific verification boundaries. See the capability matrix before assuming macOS and Windows UI parity.

A practical Codex monitoring checklist

1. Parse complete JSONL records and ignore malformed trailing fragments.
2. Use semantic start, user, and completion events.
3. Preserve a stable event or thread key for deduplication.
4. Apply freshness windows so old completions become idle.
5. Separate child-thread reminders from the provider's main status.
6. Keep session content local and make alert delivery explicit.