To monitor multiple Claude Code and Codex sessions, track every recent local thread independently. Give each thread its own state, identity, timestamp, and return target. Only then should you reduce those rows to the one Claude indicator and one Codex indicator that fit in a status bar.
Watching only the newest file fails as soon as one session waits for a reply while another keeps working. Watching only the provider process is worse: one running process says nothing about which thread finished or where the user should return.
Build one row per session
Claude Code and Codex both leave local session records, but the layouts differ. Agent Island indexes Claude transcripts under ~/.claude/projects and reads current Codex rollouts under ~/.codex/sessions. Claude Desktop also keeps titles, working directories, and activity times in its own session store.
The monitor joins those sources into a common row:
provider Claude or Codex
session stable session id
project working directory
label thread title or project name
modified latest semantic activity time
state working, your turn, stalled, or idle
turn key identity of the current turn
return target desktop session or CLI resume targetThe stable session id prevents duplicate rows. Claude Desktop may store the same CLI session under more than one project folder, so a raw directory listing can show one conversation twice. The scanner sorts by activity and keeps the newest row for each provider and session-id pair.
Automation also needs a boundary. Codex exec runs, probes, bridge sessions, and internal MCP work do not represent a human conversation waiting for attention. They are filtered from the monitor. Subagent threads are hidden by default because a fan-out can finish dozens of child tasks while the main thread is still working. Users can opt into subagent alarms when that signal is useful.
Keep classification separate from aggregation
Each row is classified before the provider-level status is chosen. A fresh completion marker may produce needsYou. Recent assistant output without a terminal marker remains working. A session that was observed working and then stops writing can become stalled. Old activity expires to idle.
That produces situations a single-file watcher cannot represent:
Claude session A: your turn
Claude session B: working
Claude session C: idle
Codex session D: stalledThe status bar still has one Claude position and one Codex position. Agent Island uses a priority order for that compression:
unacknowledged your turn
stalled
working
acknowledged your turn
idleAn unanswered turn wins because the user can act on it. Once the user acknowledges that alarm, the old completed turn drops below a working sibling. This prevents a static "your turn" indicator from hiding a different session that is actively producing output.
Within the same priority, the newest semantic activity wins. File modification time is only a fallback because bookkeeping writes can touch a file after the event that actually changed the conversation.
Alerts need thread identity
The provider-level indicator is a summary. Alert delivery stays thread-specific.
Each reminder key includes the provider, transcript or session identity, and the turn key. The same completed turn cannot alert twice just because the scanner runs again. A later turn in the same session gets a new key and can alert normally.
When another distinct alarm arrives while a panel is visible, the panel controller queues it instead of replacing the first one. When several child sessions finish in one burst, the reminder center records the group and surfaces the newest fresh turn rather than replaying a popup for every child. Those two rules solve different problems: preserve distinct human handoffs, but collapse machine-generated storms.
A reply is also part of the alert lifecycle. Filesystem activity triggers another scan. If the user has already answered and the thread leaves needsYou, the pending reminder is cancelled and any visible panel for that turn closes. An alert that cannot retract itself will eventually lie.
Use events for speed and polling for recovery
A pure timer adds visible latency. A pure filesystem watcher can miss an event after sleep, a temporary watch failure, or a burst of writes.
Agent Island combines both. Transcript writes trigger a throttled rescan with a trailing pass so the final end_turn or task_complete event is not lost behind streaming output. A six-second timer remains as the fallback. Parsing runs away from the main UI thread, then the chosen provider states are published together.
The result is fast without rescanning every file on every token. It also recovers without asking the user to reopen a terminal.
What a multi-session monitor cannot know
Local session events show activity and turn boundaries. They do not prove that a task is making useful progress, estimate time remaining, or understand whether a tool call is blocked on an external service. A quiet session may be waiting on a long command. A busy session may be repeating unhelpful work.
The monitor should report observable state, preserve uncertainty, and return the user to the right thread. It should not pretend to be a project manager or restart work on its own.
Agent Island 1.7.1 applies this model to Claude Code and Codex on the local machine. The project is free and MIT licensed. Read the companion article on distinguishing stalled, finished, and working sessions, or download the current release.