Agent Island Proposes Seven-State Taxonomy For Monitoring AI Coding Agent Sessions

The growing adoption of AI coding agents such as Claude Code and Codex has created a gap that few developer tools have attempted to fill: knowing what, exactly, the agent is doing at any given moment. A new open-source project is attempting to close that gap with a structured framework for classifying session states and a companion desktop application that puts the model into practice.

Agent Island, a free and MIT-licensed local status monitor for macOS and Windows, has published a provider-neutral taxonomy that defines seven operational states an AI coding agent session can occupy. The framework is accompanied by a test checklist intended to help developers and tool maintainers evaluate whether their monitoring actually reflects what is happening in a session, or whether it is projecting certainty where none exists.

The taxonomy and its accompanying desktop application, which has reached version 1.7.1, are aimed at a specific and growing audience: developers running AI coding agents locally who want reliable, at-a-glance session awareness without uploading their session data to an external service.

UPDATE: Agent Island v2.1.2 is now current. It supports Claude Code, Codex, Grok, Antigravity, and Cursor on both macOS and Windows, and Auto-resume has been removed. Current release, here.

The problem with treating events as states

At the core of the taxonomy is a distinction that sounds simple but carries practical weight. Events, files, processes, hooks and notifications are evidence for session states, not states in themselves.

The reference document, authored by Agent Island Creator, Tristan Tang, argues that many existing tools conflate a single signal, such as a completion marker or a burst of file activity, with a definitive session state. That conflation can produce misleading results. A completion event, for instance, does not prove that generated code is correct or that a broader task is finished. Silence does not prove that a process has crashed.

The taxonomy is designed for maintainers of developer tools, researchers comparing coding-agent workflows and teams writing operational guidance. Its stated goal is not to make Claude Code, Codex or any other tool look identical, but to make claims such as “running,” “waiting for the user” and “stalled” testable against actual evidence.

Seven states, no more

The framework defines seven primary states: inactive, running, waiting_for_user, completed, blocked, stalled and unknown. Each state requires minimum evidence before it can be assigned.

An inactive session requires no fresh evidence of an active turn, but that does not prove the session was intentionally closed. A running session requires fresh start, progress, tool-use or streaming activity tied to the current turn, but that does not prove useful work is being produced.

The waiting_for_user state requires a fresh and explicit request for permission, clarification or another required user action. It is distinct from a completed state, which requires a terminal event for the current turn with no later activity that supersedes it. The taxonomy insists these two states remain separate in the evidence model even though both might map to a user-facing “your turn” treatment.

A blocked state requires an explicit authentication, quota, policy, provider or execution failure that prevents normal continuation. A stalled state applies when a turn was running and then exceeded a documented silence threshold without a terminal or blocked event. The unknown state covers situations where evidence is missing, contradictory, unsupported or too old for any other classification.

Keeping modifiers separate from states

A significant design decision in the taxonomy is the insistence that cause, confidence, freshness and presentation be kept as modifiers rather than promoted to primary states.

Products, the document argues, often create too many states by mixing these dimensions together. The framework instead defines a set of modifier categories: reason (such as permission, authentication or rate limit), freshness (the age of the evidence at observation time), confidence (whether the state assignment is explicit, inferred or a fallback), attention level and the source of the evidence.

This separation allows a monitoring tool to communicate something like “blocked due to authentication failure” without treating every failure reason as a new top-level state. The approach is intended to keep the user-facing state set compact while preserving diagnostic detail underneath.

An evidence hierarchy for conflicting signals

When different signals point to different states, the taxonomy prescribes a precedence order. Explicit semantic events tied to the current turn take priority. Later user or agent activity that supersedes an earlier event comes next. Correlated process and session activity follows, then filesystem modification timestamps when semantic timestamps are unavailable. Silence-based inference sits at the bottom and can support a stalled classification but never a completed one.

The ordering has practical implications. A fresh completion event should override a slightly older process sample. A later user prompt should revoke that completion. A file modification timestamp should not override a structured error simply because bookkeeping touched the file afterward.

The document references related work by Manazir Ali, whose Operating Standard for Harness-Based Agents extends the same discipline to completion claims, requiring artifacts such as a commit hash, test output and exit code before trusting a reported “done.”

A checklist for testing monitors

The taxonomy includes an evaluation checklist of at least twelve tests that a session monitor should pass to be considered reliable.

These include verifying that a fresh start becomes running without inheriting the previous turn’s terminal state, that duplicate observations produce only one notification, that a later user prompt correctly revokes an earlier completed or waiting_for_user state and that silence can become stalled but never a fabricated success.

Other tests cover restart recovery, where restarting the monitor should reconstruct current state from durable evidence, as well as handling of clock skew, partial writes, privacy boundaries and the expiry of old terminal and stalled states back to inactive.

Four levels of evaluation

The framework also defines four cumulative evaluation levels for monitoring tools. Level zero, described as “display,” covers tools that show provider or process presence. Level one, “event-aware,” covers tools that recognise start, input, completion and explicit failure events. Level two, “turn-aware,” adds tracking of identity, freshness, supersession and deduplication. Level three, “operational,” covers restart recovery, multi-session handling, stale attention expiry and documented privacy boundaries.

The levels are described as cumulative and are intended to describe evidence quality rather than product quality. A focused level-one tool can be useful, the document argues, but it should avoid making level-three claims.

Agent Island v1.7.1 in practice

Agent Island itself applies a local version of the taxonomy to Claude Code and Codex sessions. It reads session artifacts already present on the user’s machine and does not upload session data to an external service.

The v1.7.1 release addressed several long-standing issues. Among them, the expanded information panel could previously open as an empty black surface due to a timing race condition in the fade-in animation. A state-driven watchdog now forces the content visible whenever the panel has been expanded for 300 milliseconds.

The release also fixed a problem where the application’s “Launch at Login” toggle would fail with an “operation not permitted” error. The issue stemmed from ad-hoc builds changing their code signature with each update, which stranded the old Background Task Management record. The toggle now clears stale records before registering, detects Gatekeeper app translocation and provides guidance to move the application into the Applications folder.

Codex token accounting corrected

A notable fix in v1.7.1 addressed discrepancies in Codex token accounting that users had reported as a 19 per cent variance against the ccusage reference tool.

Two defects were responsible. The first involved replayed token usage events where the runtime re-reported a turn’s delta without advancing the cumulative counter. Each replay was counted again, and one extended session file had accumulated more than 331 million phantom tokens. A guard now skips deltas whose cumulative pair is unchanged.

The second defect was that archived session directories were never scanned. Archiving moves rollout files out of the live tree, and 2.5 billion tokens from July had been stored only in the archive path. The remaining difference to ccusage is described as deliberate: Agent Island attributes usage to the time it occurred rather than to the session’s start day.

Alert suppression and visual refinements

The release also changed how session alerts behave when the user is already looking at the relevant session. The turn alarm no longer appears over a session the user is actively viewing. When the application hosting that session’s command-line interface is in the foreground, matched by process working directory and then up the parent chain to Terminal, iTerm, VS Code or other host applications, the alarm holds and fires only when the user switches away.

On the visual side, v1.7.1 introduced a glow colour choice in settings with four options: teal, cobalt, violet and silver. Warning amber and critical red still override the ambient colour. Visual effects are now a two-mode choice between “vivid,” which includes a continuous halo and orbit sweep, and “calm,” which removes ambient light entirely and retains only approaching-limit warnings and the attention pulse.

The macOS version also received refinements to match the application’s silhouette to the physical notch height of the display, correcting an issue where the island could hang below the real notch as a visible strip on machines where macOS draws the menu bar taller than the hardware housing.

Update checks finally working

A practical addition in v1.7.1 is functional update checking. The application now checks the newest GitHub release at launch and every six hours, presenting a two-button prompt where “Update” opens the release page and “I know” snoozes that version for seven days.

The release notes acknowledge that the Sparkle feed URL used for update checking had always been empty, meaning its update checks silently found nothing. This explains why older installations never received notifications about new versions.

Available on macOS and Windows

Agent Island v1.7.1 is available as a DMG for macOS, which now opens as a styled installer window rather than a bare Finder window, and as a zip archive for Windows. It can also be installed via Homebrew on macOS, Winget on Windows or Scoop with an additional bucket.

The project maintains its documentation and privacy boundaries on the Agent Island website, and the source code and release assets are hosted on GitHub.

Last Updated on August 11, 2026 by Nick Ross