EN 中
View on GitHub

$ cat blog/how-agent-island-reads-sessions

Engineering 5 min read

How Agent Island reads your sessions — locally, with no telemetry

No plugin, no proxy, no wrapper around your CLI. The status you see comes from files Claude Code and Codex already write to disk — plus exactly three kinds of network calls, all listed below.

A status companion has one hard requirement: it must know what your agents are doing without changing how they run. Agent Island doesn't inject itself into Claude Code or Codex at all. Both tools already journal every session to local files; the app just reads them.

Where the sessions live

Claude Code writes one JSONL transcript per session under ~/.claude/projects/<project>/<session-id>.jsonl — every user message, assistant turn, and tool result as a line of JSON. Sessions opened through the Claude desktop app additionally get a bookkeeping file under ~/Library/Application Support/Claude/claude-code-sessions/ that carries the human-readable title, the archived flag, and a cliSessionId that links back to the CLI transcript. Agent Island joins the two, so a desktop thread shows up with its real title.

Codex writes rollouts under ~/.codex/sessions/YYYY/MM/DD/. Line one is a session_meta record with the session id, working directory, and originator. One practical detail: that first line embeds the full base instructions and can run tens of kilobytes, so a fixed-size read truncates it mid-JSON — the scanner keeps pulling chunks until it actually sees the first newline.

From lines to states

The island's states — working, your turn, stalled, rate-limited, auth required — come from a small state machine over the tail of each transcript. The interesting part is what does not count as a finished turn:

  • An assistant line with stop_reason: "end_turn" normally means it's your turn. But Claude writes rate-limit banners ("You've hit your session limit…") with the same envelope, flagged only by isApiErrorMessage: true. Since 1.5.1 those never classify as done — being told to wait is not a turn.
  • Lines flagged isSidechain (older Claude Code interleaves subagent traffic into the main transcript) are skipped.
  • Codex subagent and automation rollouts are filtered at scan time — that's its own story.

File watching keeps this cheap: FSEvents triggers a rescan on transcript writes, so a finished turn usually reaches your screen in one to two seconds without polling loops.

Every network call the app makes

The usage rings need data that isn't on disk, so there is a short, complete list of what the app talks to:

  • api.anthropic.com/api/oauth/usage — Claude quota windows, using the OAuth token from your existing local Claude Code login;
  • chatgpt.com/backend-api/wham/usage — Codex quota windows, same pattern with your local Codex credentials;
  • GitHub — the Sparkle appcast and release feed for update checks, and the public repo API for the star count on this site's header.

That's the whole list. There is no Agent Island server, no account, no analytics SDK, no crash reporter. Transcript contents are parsed for state and never leave your machine. The app is open source, so this claim is checkable: search the code for URLSession / HttpClient and you'll find exactly these endpoints.

The part that acts, and why it's gated

Historical note: an earlier release included an auto-resume feature that could relaunch a session after a quota reset. That feature has been retired and is not part of the current product. Agent Island now monitors local state and alerts the user without submitting prompts or continuing a run.

If you want the even shorter version: your agents already tell the filesystem everything. Agent Island just listens to it — and interrupts you only when a human is actually needed.