A local session monitor has to answer a hard question from incomplete evidence: is the coding agent still working, waiting for the user, or simply quiet?
I help run Agent Island, a local status companion for Claude Code and Codex. Its state model starts with files the tools already write on the machine. That keeps the transcript private, but it also means every status needs a conservative evidence rule.
Recency is a filter, not a state
Claude Code and Codex can leave many JSONL session files behind. Modification time helps select recent candidates, but a recent timestamp does not tell us what happened inside a turn.
A launcher, a metadata write, or a stale process can touch a file. Treating every recent write as active work would make old sessions look alive. The scanner therefore combines recency with recent events and whether it observed the file producing output.
Old files are excluded before classification. This matters after an app restart, when the monitor sees an archive of sessions but has no reason to promote them into the current status surface.
Completion needs provider-specific evidence
The two providers do not record the end of a turn in the same way.
For Claude Code, an assistant turn with a terminal stop reason is completion evidence. For Codex, the task completion event ends the active turn. A later start event supersedes an older completion marker and returns that session to working.
This rule avoids a common mistake: mapping file silence directly to completion. Silence can mean the tool is thinking, blocked on an external process, waiting for input, or already finished. The event that ended the turn is stronger evidence than the absence of a new write.
Stalled requires observed history
A quiet file should not turn into a warning just because a timeout expired. The monitor first needs to have observed that exact session working. Only then can a long pause without a completion marker become an attention state.
That extra memory changes the false-positive profile. An untouched historical transcript stays idle. A session that produced output and then stopped without a terminal event can ask for attention.
The tradeoff is deliberate. A conservative monitor may take longer to warn about an unusual failure, but it avoids marking an entire archive as stalled after launch.
One provider can have several live sessions
Developers often run more than one Claude Code or Codex task. The UI cannot treat the newest file as the only source of truth because an older session may need the user while a newer one is still working.
Agent Island classifies current candidate sessions separately, then chooses the most urgent state for each provider. The top bar shows one Claude signal and one Codex signal, while the underlying session identity remains specific enough to route the user back to the right work.
The privacy boundary stays narrow
Local transcript evidence can support working, your-turn, and attention states. It cannot prove that generated code is correct, that a tool call was useful, or that the task achieved its goal.
The monitor also does not need to upload transcript content to a hosted state service. File recency, provider events, and observed transition history are enough for the limited question it answers.
The original engineering note describes the released state model and its limits: Detecting Session State Locally.
The useful invariant is simple: promote a session only when the evidence supports the transition, and keep quiet when it does not.
Top comments (0)