DEV Community: tristan666666

Why Long Claude Code and Codex Runs Stall, and Why I Built a Local Notch Companion

tristan666666 — Fri, 19 Jun 2026 09:11:00 +0000

Long agent runs fail in a boring way: not with a dramatic crash, but by quietly waiting for the next human action. A Claude Code or Codex session can still be sitting in your terminal, but the useful state has changed from "working" to "your turn", "stalled", or "safe to reset and resume". If you are not watching the terminal, that state change is easy to miss.

I built Agent Island as a small macOS notch/menu-bar companion for that exact gap. It watches local Claude Code and Codex sessions, shows whether a run is still active or needs attention, and can optionally help resume after a reset window. The important part is that it is local-first and opt-in: it is not trying to bypass provider limits, hide automation, or blindly press continue forever.

The actual problem is session state, not speed

When I leave a longer coding agent run going, the terminal is technically still open, but that does not tell me whether useful work is still happening.

A run can pause because a command finished, the model needs a choice, a tool is waiting for confirmation, or a reset window changed what is safe to do next. "The process still exists" is not the same as "the agent is still making progress".

The terminal is the source of truth, but it is a poor ambient notification surface. If you are working in another window, walking away for coffee, or checking another task, the important transition can happen quietly.

The states that matter

The states I care about are simple:

running: the agent is still producing output or executing useful work
your turn: the session needs human input
stalled: the run appears stuck or no longer progressing
reset-ready: enough time has passed that resuming may be reasonable

Once I named those states, the UI became obvious: it should be glanceable, quiet, and close to the place I already look on a Mac.

Why this belongs on the Mac

For local coding agents, the relevant evidence is local: terminal sessions, transcript files, app state, and user intent. I did not want a cloud dashboard for this. I wanted a small local companion that can tell me what is happening without uploading prompts or workspace content.

That is why Agent Island lives in the macOS notch/menu-bar area instead of becoming another full dashboard. It is meant to be a status surface, not a new control plane.

Why auto-resume must be opt-in

Resume automation is useful, but it is not always safe.

Blindly continuing every run can waste quota, repeat a bad command, or push a task in the wrong direction. A reset window does not mean every session should continue automatically. The right default is visibility first, automation second.

So Agent Island treats auto-resume as something explicit. You can use it for sessions you trust, but the product is not a provider-limit bypass and it does not promise to save tokens.

What Agent Island does

Agent Island is a small open-source macOS companion for people running longer Claude Code and Codex workflows.

It currently focuses on:

showing local Claude Code / Codex run state in the notch or menu bar
surfacing running / your turn / stalled / reset-ready
optional notifications when attention is needed
optional resume help for selected long-running sessions
staying local-first rather than becoming a cloud service

The launch video is here:

https://github.com/user-attachments/assets/d69b41e0-9298-4f17-b6c9-6014f3bd956b

What I learned building it

State detection is messier than checking whether a process is alive. Short pauses are normal. Transcript files can be large. A stale run and a slow run can look similar if you only sample one signal.

The biggest product lesson was that the best UX here is not a big dashboard. It is a quiet, trustworthy signal that tells you when to come back.

Source

The project is open source here:

https://github.com/tristan666666/agent-island

I would especially like feedback from people who leave Claude Code or Codex running on multi-hour local workflows. How do you currently tell whether a run is still working, waiting for you, or stalled?

How Agent Island Detects Claude Code and Codex Session State

tristan666666 — Thu, 18 Jun 2026 17:19:00 +0000

I built Agent Island around a small problem that becomes painful during long agentic coding runs: the task does not always fail loudly.

A Claude Code or Codex session may still be working, may have finished and be waiting for your next instruction, or may have frozen mid-turn. If that happens while you are away from the keyboard, the only visible signal is usually buried in a terminal or transcript file.

Agent Island turns that into a local macOS signal in the MacBook notch / menu-bar area:

working: the provider logo breathes
your turn: the provider logo spins
stalled: the provider logo turns red and can play a short beep sequence

Launch video: https://github.com/user-attachments/assets/d69b41e0-9298-4f17-b6c9-6014f3bd956b

Repo: https://github.com/tristan666666/agent-island

Download DMG (macOS 13+): https://github.com/tristan666666/agent-island/releases/download/v1.0.0/AgentIsland-1.0.0.dmg

The data source is local

There is no shared live-state API for Claude Code and Codex CLI sessions, so Agent Island reads the same local artifacts the tools already write.

Claude Code activity is detected from JSONL transcript files under:

~/.claude/projects/*.jsonl

The trigger picker uses Claude Desktop's session store for nicer labels and archived filtering:

~/Library/Application Support/Claude/claude-code-sessions/local_*.json

Codex activity is detected from recent JSONL sessions under:

~/.codex/sessions/YYYY/MM/DD/*.jsonl

For Codex session labels, Agent Island reads the first session_meta JSONL event and uses its id and cwd.

This keeps state detection local. The app does not need a third-party service just to decide whether a session is still moving.

The state model

The scanner runs every six seconds and classifies each candidate transcript. File I/O happens off the main actor so the notch UI stays responsive.

The core inputs are:

transcript modification time
the last few JSONL events
whether this app has recently observed the file producing output

The current thresholds are intentionally conservative:

Signal	Threshold	Meaning
active window	18 seconds	Fresh transcript writes mean the session is working.
stall after	300 seconds	A watched working session that freezes mid-turn for 5 minutes becomes stalled.
stall cap	15 minutes	Past this, the app treats it as idle rather than a live stall.
needs-you cap	20 minutes	A finished turn is only surfaced as "your turn" while it is still fresh.
attention window	30 minutes	Old transcripts are ignored.

That last point matters. Agent Island only sounds the alarm if it first saw the session working. A transcript that was already old when the app launched should not suddenly become a red alert.

Detecting "your turn"

Agent Island tails the last 128 KB of the transcript, capped to 200 lines, so a recent completion marker is unlikely to be pushed out by a burst of tool output.

For Claude Code, the scanner looks for an assistant event whose stop reason indicates the assistant turn is complete:

stop_reason: end_turn
stop_reason: stop_sequence
stop_reason: stop

For Codex, the scanner looks for Codex event messages:

payload.type: task_complete

If a newer task_started appears before a completion marker, Codex is treated as still working.

Detecting stalled sessions

A stalled session is not just "a file did not change for a while." That would be too noisy.

The scanner only returns stalled when all of these are true:

the transcript was recently observed in the working state
the transcript has stopped changing for at least five minutes
no fresh turn-complete marker is visible in the tail
the session is still inside the 15-minute stall cap

This catches the failure mode the app cares about: a long-running agent that was active, then froze mid-turn while you were not watching.

Aggregating per provider

Claude and Codex can each have multiple candidate transcripts. Agent Island classifies each file, then takes the most urgent state for that provider:

idle < working < your turn < stalled

That gives one visible Claude state and one visible Codex state in the notch.

Auto-resume is separate from state detection

The visual state monitor is passive. Auto-resume is explicit and opt-in.

A trigger contains:

provider: Claude or Codex
session id
working directory
message to send
trigger mode
enabled state
last fired time

There are two trigger modes:

after reset: fire once after the provider's real reset boundary advances
every N hours: fire on a fixed local interval

The reset-based mode is deliberately not "wait five hours from now." The app watches the provider usage store and treats a changed reset boundary as the reset signal. That prevents relaunches from firing immediately and lets the app catch up once if the Mac slept through a genuine rollover.

The risk boundary

When a trigger fires, Agent Island resumes the selected CLI session using the provider's resume command. Those flags are powerful: they bypass normal approval prompts and can spend tokens.

That is why auto-resume is not the default experience. The app makes it explicit in the README and UI: only attach triggers to sessions you trust.

Why this belongs in the notch

This is not trying to replace a terminal UI, dashboard, or session browser. Those are useful when you want detail.

The notch is for a narrower job: a persistent, low-friction signal that answers one question while you work on something else:

Is my agent still moving, waiting for me, or stuck?

That is the surface Agent Island optimizes for.

Feedback is welcome, especially from people who run Claude Code or Codex for long refactors and maintenance tasks.