DEV Community: Agent Island

Stop Background Agents From Triggering Foreground Alerts

Agent Island — Wed, 15 Jul 2026 17:32:01 +0000

A background review worker finishes while the main coding-agent session is still running. If the monitor scans for the latest completion marker, it tells the user to return too early.

The fix starts with source classification.

Claude sidechains

Claude records may place workers in subagents files or interleave lines marked isSidechain into the main transcript. The main parser skips sidechain lines. Separate agent transcripts enter normal monitoring only when subagent alerts are enabled.

Tests cover both dangerous orders: a sidechain end_turn after the main assistant starts a tool, and trailing sidechain traffic after the main assistant really finishes.

Codex rollout sources

Codex session metadata distinguishes interactive CLI work from exec, internal activity, and structured subagents. A foreign originator is treated as automation even if another field resembles a worker.

interactive -> normal status
subagent     -> opt-in alerts
automation   -> no user-turn alert

Classification happens before sessions are reduced to one provider-level state. Otherwise the monitor loses the identity needed to remove a worker's false completion.

I help run Agent Island, where this filter protects local Claude Code and Codex alerts. This draft stays on publication hold pending canonical verification.

Why a Coding-Agent Completion Event Is Not Enough

Agent Island — Wed, 15 Jul 2026 17:31:34 +0000

A terminal monitor sees task_complete. It sends an alert. The user returns and finds that the event belongs to an old turn, a background worker, or a session they already resumed.

The parser found a real event. The product state was still wrong.

Return more than a boolean

Our local parser returns a completion flag, a turn key, and the event's semantic timestamp. The turn key deduplicates repeated observations. The timestamp lets later activity revoke the result.

TurnStatus {
  isDone
  turnKey
  activityDate
}

Claude and Codex need separate adapters. Claude stop reasons are not sufficient on their own because an API-error record can use a completion-shaped envelope. Codex uses event types such as task_complete and turn/completed.

Treat completion as a lease

The monitor combines the turn timestamp with newer local session activity. A fresh completed turn becomes needsYou. Newer user activity can move it back to working, while the freshness cap eventually returns it to idle.

Filesystem modification time remains a fallback. It cannot be the main clock because bookkeeping writes do not carry the same meaning as user activity.

Tradeoffs

A longer attention window preserves alerts for users who step away, but keeps old state around longer. Watchers improve latency, but a periodic scan is still needed for dropped events. Upstream record changes require parser fixtures that cover errors and later activity, not just the happy path.

I help run Agent Island, where this state model is used for local Claude Code and Codex monitoring.

A Finish Notification Is a Lease, Not a Boolean

Agent Island — Wed, 15 Jul 2026 08:15:33 +0000

A coding agent finishes a turn. The monitor schedules an alert. Two seconds later, the developer has already replied.

Should the notification still appear?

If completion is stored as a boolean, the answer is usually yes. The alert was scheduled from a true value, and the delayed task has no reason to question it. The result is a technically accurate notification that is already obsolete.

We found it more useful to model a completion as a short-lived lease on human attention. The lease has an identity, a freshness boundary, and a condition that can disappear before or after delivery.

Detection is not permission to interrupt

The local session scanner and the reminder system answer different questions.

The scanner asks whether the latest meaningful evidence says the agent ended a turn. The reminder system asks whether this is a new handoff that still needs the user.

That separation matters at startup. A completed transcript may be correct status information, but it is not necessarily new information. Replaying every completion found on disk when the app opens would turn accurate history into noisy alerts.

Agent Island therefore baselines completed turns it discovers at startup. They can appear in the status surface without being treated as newly created interruptions.

Re-check state at delivery time

Local session files change quickly around a handoff. A user can return to the terminal before a notification delay expires. A client can also append bookkeeping data after the assistant's terminal event.

The reminder is scheduled with a short delay, then validates the current state again:

alerts enabled
+ same turn still needs attention
+ turn has not been acknowledged
+ turn has not already been delivered
= show the alert

The second check is the important part. A delayed task should not trust the snapshot that created it.

This pattern applies beyond coding agents. Any notification based on a reversible condition should verify that condition immediately before interrupting the user.

Give the handoff a stable identity

Deduplicating on provider name is too broad. One Claude session can finish several turns. Deduplicating on the latest file timestamp is too narrow because the same turn can be observed through repeated scans.

The delivery key needs enough context to identify the handoff: provider, session, project, transcript, and turn identity. Repeated observations of that key are one event. A later turn gets a different key even when it belongs to the same session.

Delivered and acknowledged keys are retained for a bounded period. That prevents a refresh from replaying an old alert without turning the reminder layer into a permanent transcript database.

Cancellation has to work after delivery too

Preventing an alert before it appears solves only half of the stale-state problem.

The user may reply from another window while the notification panel is already visible. On each scan, the reminder layer compares the current attention keys with the previous set. When a key disappears, it cancels the pending task and dismisses the corresponding visible alert.

The UI follows the source condition instead of asking the user to close evidence that is no longer true.

Bursts are one human event more often than many

Agent workflows can finish several child sessions within seconds. The filesystem sees multiple completions. The person supervising the run may see one parent workflow reaching a handoff.

Delivering every child completion optimizes for event count, not attention. The reminder layer selects the newest relevant turn and baselines the rest of the burst. Subagent alerts remain opt-in because child-session traffic can otherwise dominate the signal from the main session.

The return action must be honest

A useful alert identifies the provider, project, and session. Its action should return the developer to that work.

For a Claude CLI session, a known session ID can be resumed in a terminal. Claude Desktop does not expose the same exact-conversation routing contract. In that case, activating the app and copying the session title for search is more honest than labeling an imprecise action as a guaranteed deep link.

Platform limits belong in the interaction design, not in a footnote after the button fails.

What the signal does not prove

"Your turn" means the local evidence says an agent ended a turn and a response is still needed. It does not mean the generated code is correct, the task is complete, or the output is safe to merge.

That boundary keeps the alert useful. The monitor owns attention state; the developer still owns verification.

The full setup and behavior guide is here: Get notified when Claude Code finishes.

Agent Island is open source for macOS and Windows: source and releases.

The Last JSONL Line Is Not a State Machine

Agent Island — Wed, 15 Jul 2026 07:24:09 +0000

A transcript ended with an assistant message. Is Claude Code finished?

Not necessarily.

That line may be the end of the current turn. It may belong to an old session. Claude Desktop may have written bookkeeping metadata after it. The user may already have replied. Or the assistant message may actually be an API error carrying a stop reason that looks deceptively final.

This is the awkward part of building a local status monitor: parsing JSONL is easy. Deciding what the evidence means right now is the engineering work.

File activity is evidence, not state

Claude Code and Claude Desktop already leave useful records on the machine. A local companion can inspect them without shipping transcripts to a hosted service. That gives us a strong privacy boundary, but it also removes the convenience of asking a server for a single authoritative status.

The first implementation temptation is to map modification time directly to state:

modified recently -> working
not modified -> idle

It fails in both directions. A session may be working while writes arrive in bursts. A metadata write may touch a file after the actual turn ended. A quiet file may mean the model is thinking, waiting on a tool, stalled, or simply abandoned.

The timestamp is useful, but it cannot carry the whole decision.

Completion has to survive newer noise

For Claude, a terminal assistant event is one input to the your-turn decision. The scanner also tracks the event identity and semantic timestamp. That matters because Claude Desktop can update its activity record a few seconds after the final assistant event.

If every newer desktop timestamp meant "the user came back," that bookkeeping write would erase the completion state before the alert fired. We give that short post-completion write a grace window. Activity well after the grace is different: it is evidence that the user probably returned, so the old completion should be suppressed.

This distinction came directly from observed event ordering. It is not something a generic file watcher can infer.

A new turn cancels the old answer

The parser works from the latest meaningful main-thread event, not merely the last physical line. A user event after an assistant completion means the old handoff is over. A streaming assistant event without a terminal stop remains working.

Sidechain events need separate treatment. Tool and subagent traffic can appear after the main assistant event. Letting a sidechain completion finish the main turn creates noisy alerts; letting trailing sidechain lines hide a real main-thread completion loses alerts. The parser therefore identifies the latest relevant main-thread event first.

API errors are another trap. A rate-limit response may be represented as an assistant line with a stop reason. That is attention, but it is not a successful your-turn completion. The error marker must win.

State needs an expiry policy

Even a correctly detected completion is not fresh forever.

Our scanner keeps bounded windows for working, your turn, stalled, and attention. A session previously observed as working can become stalled after sustained silence. A completed turn eventually ages back to idle. Evidence outside the attention window is ignored.

The exact thresholds are implementation details that may change. The invariant is more important:

old evidence must not create a new interruption

That rule also applies at app launch. Existing completed turns become baseline history. We do not pop an alarm for every session that finished before the monitor started.

Multiple files still have to become one signal

A real machine can have duplicate Claude Desktop records, archived threads, main transcripts, and subagent transcripts. A status bar cannot render that raw inventory.

The monitor filters archived and machine-driven sessions, deduplicates repeated session IDs, and then chooses the most urgent current state for the provider. Subagent alarms remain opt-in because orchestration can finish many child turns in a burst while the human only cares about the parent workflow.

This is less impressive than claiming "real-time AI observability," but it is more useful. The user needs one defensible answer: working, your turn, or attention required.

Tests should encode event order, not just fixtures

The regression cases that matter are sequences:

assistant completion, then a user reply;
completion, then a short bookkeeping write;
completion, then genuine later desktop activity;
sidechain completion after unfinished main output;
API-error assistant line with a stop reason;
old semantic activity with a freshly touched file.

Each sequence protects a state transition. A parser test that only checks whether one JSON object can be decoded would miss the actual failures.

The boundary

A local monitor can tell us that Claude is producing output, ended a turn, or appears to need attention. It cannot prove the requested task is correct or that generated code is safe. "Your turn" means a reply is needed, not that the engineering work is done.

Agent Island uses this local model for its Claude Code and Codex status surface. The longer engineering guide, including the freshness boundaries and released scope, is here: Claude Code status monitor.

The project is open source: inspect the scanner and tests on GitHub.

Why a Local Token Estimate Is Not Your Claude or Codex Bill

Agent Island — Tue, 14 Jul 2026 14:15:13 +0000

A token log can support a dollar estimate. It cannot tell you what a subscription cost.

The distinction sounds obvious until a report card shows a large number. Without a visible definition, readers interpret it as spend or savings. The implementation needs an accounting rule before it needs a chart.

Calculate by token category

For each local usage event, keep input, output, cache creation, and cache reads separate. Apply the matching per-million rate to each category and add the results.

value = input * input_rate
      + output * output_rate
      + cache_create * cache_create_rate
      + cache_read * cache_read_rate

Each token quantity is divided by one million in the actual calculation. The rate table must carry a snapshot date.

Codex needs an extra parsing step because its input count includes cached input. Subtract the cached portion first, then price normal input and cache reads separately. Otherwise the cached tokens are charged twice in the estimate.

Do not guess unknown models

A newly released model can appear before the embedded table knows its rate. Assigning a nearby model's price makes the total look complete but weakens its meaning.

The macOS v1.6.1 implementation I work on prices a named model missing from the rate table at zero and records an unpriced warning. A Codex row received before model context instead uses the parser's gpt-5.4 model fallback. The displayed total can be low, but the gap is visible and correctable.

Define the claim

API value means the value of recorded token activity under a dated API-price snapshot.

It does not mean:

subscription spend;
money saved;
revenue;
an exact provider invoice.

Actual spend requires billing records, credits, taxes, discounts, and contract terms. Local session logs do not contain that information.

Keep volume separate

Wire-token volume includes cache activity. API value applies different prices to each category. A cache-heavy week can have a large token count and a much smaller value estimate than its headline suggests.

Showing both measures is useful. Naming them precisely prevents one from borrowing the meaning of the other.

I build Agent Island, and this article describes the released macOS calculation. The broader rule applies to any local usage tool: date the prices, preserve cache semantics, expose unknown models, and never label a counterfactual as a bill.

The full definition and implementation boundaries are documented on the Agent Island Blog.

Parsing Claude Code and Codex Logs Without Double-Counting a Week

Agent Island — Tue, 14 Jul 2026 14:10:54 +0000

Adding every token number found in a JSONL file produces a convincing but unreliable report.

Claude Code and Codex record usage differently. Claude assistant messages expose separate input, output, cache-creation, and cache-read fields. Codex rollout files split the active model and the per-turn usage across different row types. A local ledger needs to preserve those differences before it can combine anything.

Normalize at one boundary

The Claude reader accepts assistant messages with a usage object. It deduplicates a row only when both message ID and request ID exist, skips synthetic model placeholders, and keeps the four token categories separate.

The Codex reader carries the model from turn_context into later token_count events. It uses last_token_usage, not the cumulative total, because cumulative values can repeat earlier work in forked sessions. Cached input is included inside Codex input, so it is subtracted before the remaining input is priced.

Both readers then emit the same event shape:

provider, timestamp, model,
input, output, cache_creation, cache_read

Everything after that point operates on normalized events rather than provider-specific JSON.

Use calendar buckets for a calendar report

The weekly card covers today and the previous six local calendar days. The per-model slice uses that same boundary.

A rolling 168-hour model slice looks reasonable, but it can include part of an eighth calendar day. The model rows then exceed the daily-bar total. Sharing one midnight-aligned boundary removes that mismatch.

The aggregate keeps two token measures. Wire tokens include cache activity; the narrower measure includes input and output. Estimated API value is calculated separately with dated per-token rates.

Keep the share path local

The report image is rendered on the machine. The app writes it to the clipboard or opens the system share picker only after the user clicks a button. It does not upload the report or transcript.

local logs -> token events -> daily aggregates -> local image

That short path is easier to explain and inspect than an analytics-backed report service.

Tradeoffs

Deleted logs cannot be recovered. Local formats can change. A named model missing from the embedded price table is priced at zero and should produce an unpriced warning. An early Codex row with no model context is a separate case: the parser applies its gpt-5.4 model fallback. A token count also says nothing about code quality.

I build Agent Island, the open-source app whose macOS v1.6.1 implementation this article describes. The useful lesson is independent of the app: normalize provider records once, preserve cache semantics, and align every report component to the same time boundary.

The full engineering article and source context are available on the Agent Island Blog.

Hello DEV: Building Agent Island for Claude Code and Codex

Agent Island — Tue, 14 Jul 2026 12:47:59 +0000

Hi DEV — I'm the maker of Agent Island, a free and open-source status companion for Claude Code and Codex.

I built it around a simple problem: coding agents often finish, need input, or hit an error in another window while you're focused elsewhere. The work may be done, but the handoff is easy to miss.

Agent Island makes those session states visible in one place. It shows which agent and project need attention, sends a notification, and can play a sound when it is your turn. The product is local-first, and session state stays on the machine.

I'm here to share practical notes from building and shipping a cross-platform developer tool, including:

designing reliable state detection for long-running agent sessions
building useful notifications without creating noise
keeping the product local-first
shipping for macOS and Windows
learning what developers actually need from agent observability

The project is available at agent-island.dev.

I'm especially interested in how other developers manage several agent sessions at once. What part of that workflow creates the most friction for you?