How to Rank Multiple Claude Code and Codex Sessions by Urgency

Agent Island v1.7.1 introduces a priority-based ranking system for multiple Claude Code and Codex sessions, prioritizing unacknowledged handoffs and stalled sessions over recent activity. The open-source macOS and Windows monitors use a two-stage reducer that sorts by priority first and modification time second, ensuring the most actionable session represents the provider.

A menu-bar monitor has room for one Claude or Codex state, even when five sessions are active. That constraint turns a UI detail into a policy question: which session should represent the provider? The wrong answer is usually the transcript that changed most recently. Modification time tells us which file wrote last. It does not tell us which session deserves the user's attention. A background worker can append routine progress after another thread has stopped at a permission prompt. A recently acknowledged handoff can also stay in a needs-you state while a sibling resumes useful work. If a monitor is newest-first, low-value activity can hide the one session where the next action belongs to the user. A safer reducer has two stages: Recency should only break a tie between states with the same priority. In Agent Island v1.7.1, the released macOS and Windows monitors use this ordering: unacknowledged needs-you = 4 stalled = 3 working = 2 acknowledged needs-you = 1 idle / auth / rate limit = 0 An unanswered handoff wins because the user owns the next useful action. A stalled session comes next because an anomaly should not disappear behind routine progress. Working remains visible when nothing more urgent exists. The subtle case is an acknowledged handoff. It still belongs to the thread history, but it should rank below a working sibling. Otherwise, one dealt-with request can pin the provider icon and make the whole system look frozen. After assigning priority, sort by priority first and modification time second: js ranked = sessions .filter provider .map session = session, priority session .sort priority descending, modified descending providerState = ranked.first This preserves deterministic behavior without letting timestamps define policy. The tests should vary state and time independently. An older unanswered handoff must beat a newer working session. The newer of two working sessions should win their tie. Those are different rules, and a good test suite makes that difference explicit. The provider icon needs one representative session. The reminder queue must retain every open handoff. Conflating those two jobs causes another class of bugs. If the implementation reduces the provider to one session and then derives notifications from that winner, one thread's acknowledgement can accidentally cancel another thread's alarm. Agent Island instead chooses one best session for display while separately collecting every needs-you thread. Reminder identity includes the provider, session, and turn. Two waiting threads remain two obligations even though the menu bar shows one aggregate state. A compact test matrix looks like this: The aggregate state is a display decision, not evidence that other sessions stopped existing. Never overwrite the per-thread records used for deep links, reminders, or diagnostics. That boundary keeps future policy changes possible. The UI can change its ranking without losing the underlying truth. The tagged v1.7.1 implementation is open source for both platforms. The general lesson applies to any developer tool that compresses concurrent workers into one status surface: Aggregate by actionability, retain per-worker identity, and use recency only to settle equals. The full implementation notes and test boundary are in the canonical engineering article https://agent-island.dev/blog/multi-session-state-priority/?utm source=devto&utm medium=content distribution&utm campaign=multi session state priority . The v1.7.1 source and release https://github.com/tristan666666/agent-island/releases/tag/v1.7.1?utm source=devto&utm medium=content distribution&utm campaign=multi session state priority are public under MIT.