DEV Community: Agent Island

A quiet transcript does not prove a coding agent has stalled

Agent Island — Fri, 31 Jul 2026 06:44:00 +0000

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.

A macOS updater has two jobs: discover and verify

Agent Island — Fri, 31 Jul 2026 06:40:47 +0000

A desktop updater has two separate jobs: find the new release and reject an untrusted package. Treating those as one step makes failures hard to diagnose.

I help run Agent Island, a local status companion for Claude Code and Codex. The macOS build exposed this distinction clearly while we worked on its update path.

Discovery is only a version lookup

The current app checks GitHub Releases shortly after launch and then every six hours when automatic checks are enabled. The response provides a tag and a public release page. A numeric dotted comparison decides whether the tag is newer than the installed version.

That mechanism can answer one question: does a newer public release exist?

It cannot prove that a downloaded application is authentic. A network filter can also block the GitHub API while the installed app continues to run normally.

Verification belongs to the installer

The macOS build also includes Sparkle. A release appcast declares the version, package URL, and EdDSA signature. Sparkle verifies that signature against a public key embedded in the installed app before it accepts the update.

The private signing key stays in the maintainer keychain and the release workflow secret. A changed download URL cannot produce a valid package without that key.

This gives the update path two explicit boundaries:

GitHub release discovery decides which version is current.
Sparkle signature verification decides whether an update package is trusted.

A failure in the first boundary should report a version-check problem. A failure in the second should report a signature or installation problem.

Old installs need an honest migration path

An updater framework can exist while its feed is empty or its discovery path is incomplete. In that state, telling users to wait for a prompt is wrong. They need a manual comparison against the latest public release, followed by a direct download or package-manager upgrade.

From Agent Island v1.7.1, the app adds the GitHub-backed version nudge. Builds older than that may need one manual update before they enter the current path.

First launch is a different trust decision

Agent Island does not currently use a paid Apple Developer account. The macOS package is ad-hoc signed rather than notarized, so the first launch requires Finder's right-click and Open flow.

That Gatekeeper decision is separate from Sparkle's update signature. The first controls whether macOS permits the downloaded app to run. The second protects later update packages.

Disabling Gatekeeper globally would collapse a useful system boundary. A per-app first launch keeps the check narrow.

What to record when an update fails

A useful report needs only a few facts:

installed version;
macOS version;
direct DMG or Homebrew install;
result of Check now;
whether discovery failed or installation failed;
exact visible error text.

It does not need Claude Code transcripts, provider tokens, OAuth data, or private project paths.

The full implementation note and current release boundary are documented in the original article: Verifiable macOS Updates.

The source is MIT licensed, so the release and updater code can be inspected directly.

Filesystem Events Are Wake-Up Signals, Not a Session Ledger

Agent Island — Wed, 29 Jul 2026 18:53:21 +0000

A filesystem callback can arrive twice, arrive late, or never arrive. Treating each callback as an application-state transition makes a session monitor fast but fragile.

The safer design uses native events as wake-up signals. A relevant path schedules a bounded rescan. The parser reads current transcript evidence and decides the state. Periodic polling repairs any notification the operating system did not deliver.

Polling alone sets a latency floor

With a six-second polling interval, a correct your-turn state can appear six seconds late even when parsing takes milliseconds. Lowering the interval reduces the delay but increases idle scans across every known transcript root.

Native events remove that floor for ordinary writes. They tell the monitor that something changed under a watched root, so it can scan immediately.

The event does not need to describe the state change. It only needs to wake the classifier.

macOS watches roots, then filters paths

The macOS implementation uses one FSEvents stream over the existing Claude project, Codex session, and Claude Desktop metadata roots. It requests file-level events with a short latency.

The callback filters for transcript .jsonl files and the relevant Claude Desktop records. A matching path calls one change handler.

Parsing stays outside the callback. FSEvents may coalesce changes, so the handler asks, "What is true now?" rather than trying to replay an assumed sequence from notification flags.

Windows uses the same rule with different plumbing

Windows creates a FileSystemWatcher for each existing root and watches recursively. Changed, created, and renamed events can all indicate new session evidence.

One save may produce several callbacks. Atomic replacement may look like a rename. Each relevant callback therefore schedules the same rescan operation instead of applying a different state mutation.

The two platforms share the wake-up contract, not watcher syntax.

Keep polling for repair

Native notification channels are optimized for speed, not durability.

FSEvents can combine nearby changes. FileSystemWatcher has a finite buffer that can overflow during a burst. A root may appear after startup, and permissions can prevent a watcher from attaching.

Periodic polling covers those cases:

discover roots that were missing at startup;
rescan bounded transcript tails;
restore the correct state after a missed or coalesced event.

The fallback should stay bounded. Recovery is not a reason to reread every transcript from byte zero.

Coalesce the work, not the truth

A burst of callbacks should not launch a burst of full refreshes. Coalesce nearby wake-ups, serialize the refresh path, and let another pass run when activity arrives during a scan.

Only the parser decides session state. Watchers and timers merely request another observation. This keeps retries idempotent and prevents callback count from becoming business logic.

Test recovery separately from latency

An event-triggered scan proves the fast path. It does not prove recovery.

Test both:

append a completion event and verify the native watcher wakes the classifier;
disable or bypass the watcher, then verify polling reaches the same state;
create a transcript root after startup and verify a later sweep discovers it;
send repeated callbacks and verify they do not duplicate a turn alert.

I help run Agent Island. The public v1.7.1 macOS build uses FSEvents, the Windows build uses FileSystemWatcher, and both retain periodic scanning.

Read the complete watcher and polling design

Your Alert Code Should Not Parse Claude and Codex Logs

Agent Island — Wed, 29 Jul 2026 18:51:33 +0000

A completion alert becomes unreliable when every consumer interprets raw agent logs for itself.

Claude Code and Codex both append JSONL records, but they do not use the same event envelope. Claude completion can appear in message.stop_reason. Codex uses event names such as task_complete and turn/completed. If the menu bar, notification code, and session list each parse those details, they will eventually disagree.

Put provider details behind three fields

The rest of the application only needs a small result:

isDone       did the newest relevant event hand control back?
key          which turn does this result describe?
activityDate when did the semantic event happen?

The Swift implementation calls this SessionTurnStatus. The Windows port uses the same fields in a C# record struct. Code above that boundary can reason about a completed turn without knowing which provider produced the evidence.

Read from the newest evidence backward

An older completion record stops being current as soon as a new user message begins another turn.

The classifier therefore scans a bounded transcript tail in reverse and stops at the first recognized event. A new user event returns a working state. A provider-specific completion event returns done. Unknown records are skipped instead of being treated as idle.

This ordering rule matters more than the exact JSON property names. A forward scan that remembers the last completion can report a stale handoff after work has already resumed.

Exclude valid records with the wrong meaning

A JSON record can be well formed and still be the wrong completion signal.

Claude Code can emit an assistant envelope with stop_sequence for an API or rate-limit error. The record also carries isApiErrorMessage: true. Checking the stop reason alone would fire a false your-turn alert.

Subagent events need a similar guard. An isSidechain completion belongs to a background chain, not the parent conversation. Letting it complete the foreground session confuses valid evidence with relevant evidence.

These exclusions live in both platform classifiers and in the fixture set. Porting the rule without the failure examples would make parity temporary.

Keep one turn identity

Filesystem events and polling can classify the same turn more than once. The result needs a stable key so alert code can deduplicate it.

The classifier prefers identifiers already present in the record, including uuid, id, turn_id, item_id, and call_id. It derives a bounded fallback only when the provider gives no usable identifier.

Notification code should consume that key. Rebuilding identity from a file path or scan timestamp creates a second, incompatible definition of a turn.

Test traces instead of isolated helpers

The useful fixtures resemble failures from real transcripts:

an old completion followed by a new user event;
a sidechain completion after a parent event;
an API-error envelope with a completion-like stop reason;
old and current Codex completion event names.

Run the same semantic cases against the Swift and C# adapters. When a provider changes its event format, update the shared truth table first, then each parser.

The boundary is deliberately narrow. isDone does not prove that the task succeeded or that generated code is correct. It only says that the newest recognized transcript evidence handed control back to the user.

I help run Agent Island. The state contract and the platform-specific classifiers described here are in the public v1.7.1 macOS and Windows builds.

Read the full state-contract guide

Claude Desktop and Claude Code Are Different Windows States

Agent Island — Wed, 29 Jul 2026 01:14:10 +0000

On Windows, Claude Desktop, Claude Code, and provider usage are related, but they are not one state machine. A status companion needs to keep three boundaries visible.

Three independent signals

Application state describes whether Claude Desktop is running, minimized, hidden, closed to background, or unavailable.

Claude Code session state describes whether an exact coding session is working, waiting, needs input, errored, finished, or stale.

Usage state describes the provider-reported quota window and whether the local credential used to read it is valid.

A valid Claude Desktop subscription does not prove that a Claude Code usage credential is available. A closed window does not prove the desktop process stopped. A stale transcript does not prove that the application cannot be restored.

Restore the right surface

When a user selects an exact row, retain the provider and session identity that produced it. Restore logic should determine which application surface owns that identity and then use the supported Windows activation path. Sending every Claude-related row to one generic launch command loses context.

Windows applications can remove their visible window while a process or tray component remains active. A monitor should distinguish no visible window from no process and verify the result after requesting activation. Starting another process repeatedly can create duplicates without restoring the intended conversation.

Keep usage failures scoped to usage

If a usage request cannot authenticate, report that usage is unavailable. Preserve independently observed session state unless its own evidence changed. This prevents a quota credential failure from making a healthy local coding session look broken.

A useful test sequence is simple: open Claude Desktop and Claude Code separately, verify exact identity, close Desktop to background, restore it, invalidate only the usage credential, and confirm session state remains intact.

Agent Island is a free, open-source status companion for Claude Code and Codex on Windows 10/11 and macOS. It uses local session records for status and your-turn alerts, has no Agent Island account, and does not upload session data. I help run Agent Island; the full guide is here:

Claude Desktop vs Claude Code status on Windows

Stop Rescanning Every Claude Code Transcript

Agent Island — Wed, 29 Jul 2026 01:12:31 +0000

A transcript monitor can poll frequently without becoming expensive. The problem is not the timer by itself; it is treating the entire archive as the hot path on every tick.

When a developer has months of Claude Code history, reopening every transcript and parsing a tail from every file makes steady-state work proportional to archive size. It also creates correctness risks: a tail can begin in the middle of a JSON line, older completion evidence can outrank a newer handoff, and multiple sessions can be collapsed into one global answer.

Separate discovery from ingestion

Use a lightweight discovery pass to retain file identity, size, and modification time. Only a new or changed file should enter the parsing queue. A known transcript should resume from its last complete byte offset rather than being reread from the beginning.

An append-aware cursor needs five behaviors:

retain the last complete offset per transcript;
read only the appended range when the file grows;
carry an incomplete trailing line into the next read;
detect truncation or replacement and re-bootstrap safely;
preserve the newest semantic evidence for the exact session.

The cursor is an optimization only if recovery is correct. A smaller file, changed identity, or invalid continuation should trigger a bounded rebuild instead of silently dropping records.

Keep state semantics independent from I/O savings

Reading fewer bytes does not justify guessing. Keep provider and session identity, compare ordered timestamps, and distinguish working, waiting, your-turn, error, finished, and stale evidence. Silence describes freshness; it does not prove successful completion.

Measure files inspected, bytes read, parse failures, queue depth, and scan duration. Test with a large archive. Healthy steady-state cost should scale with changed files and appended bytes, not total history.

Agent Island is a free, open-source status companion for Claude Code and Codex on macOS and Windows. It reads local session records to show status and your-turn alerts, uses no Agent Island account, and does not upload session data to Agent Island. I help run Agent Island; the detailed engineering guide is here:

Monitor large Claude Code transcript archives efficiently

Review Multiple Coding Agents as a Queue of Evidence

Agent Island — Tue, 28 Jul 2026 01:21:00 +0000

Running several coding agents in parallel creates a review problem before it creates a compute problem.

The bottleneck is rarely opening another terminal. The bottleneck is deciding which session deserves attention, who owns each change, and what evidence is sufficient to accept the result.

A wall of chat windows does not answer those questions. A team lead needs a queue of owned artifacts and review decisions.

Partition work before parallelism

Every task should have one owner, one requested artifact, and one write scope. If two sessions may edit the same file, decide who integrates the final change or serialize the work.

This is the first control because parallel execution without ownership only moves conflict resolution into the review phase. The sessions may all finish successfully while the combined change remains impossible to accept.

A useful task card names:

the requested behavior;
the permitted files or subsystem;
the validation command;
the evidence expected at handoff;
the observable stop condition.

The session identifier should travel with the task card, evidence, and final review decision.

Rank states by required human action

Not every active session deserves equal attention. A practical queue sorts states by what the lead must do next:

Approval or input required. Work cannot continue without a human decision.
Failed verification. The artifact exists, but tests, build, or runtime checks failed.
Ready for review. A bounded change and evidence packet are available.
Running. The session is making progress and needs no intervention.
Idle or stale. No current action is required, but ownership may need cleanup.

This ordering prevents a noisy long-running task from hiding a small task that is waiting for one approval.

Require a review packet

A session's final message is a claim. The review packet is the evidence behind it.

For code changes, that packet should include the diff scope, diagnostics, build or test result, and a real usage check when the change has a user-facing surface. For research or operations, it should include source URLs, receipts, read-back state, and any unresolved uncertainty.

The team lead should be able to answer three questions without reopening the whole transcript:

What changed?
What proves it works?
What could still be wrong?

If the packet cannot answer those questions, the item is not ready for review.

Review risk before chronology

The oldest completed task is not always the next one to review. Sort by blast radius and reversibility.

Authentication, permissions, migrations, deployment configuration, and shared contracts deserve attention before isolated copy changes. An easily reversible local edit can wait behind an externally visible action even if it finished first.

This is also why session status should remain separate from artifact status. A session can be complete while its change is still unreviewed, rejected, or blocked from integration.

Integrate only after acceptance

Do not let “agent finished” become “change shipped.” Keep explicit states for ready, under review, accepted, integrated, and verified after integration.

That sequence protects the team from two common errors: merging a plausible result without evidence, and losing track of a good result because the session that produced it has already closed.

Keep the dashboard observational

A lead's status companion should make ownership, urgency, and evidence easier to see. It should not silently approve commands, merge changes, or deploy releases. Consequential actions belong in the system that owns them, where permissions and audit history already exist.

The useful interface is therefore compact: session identity, owner, current state, affected artifact, latest evidence, and the next human decision. More transcript text usually creates more scanning, not more control.

Parallel coding agents become manageable when the unit of coordination is not the chat session but the reviewable artifact. The lead is operating a queue of decisions, with sessions supplying evidence into that queue.

A complete implementation checklist is available in the team lead multi-agent review workflow.

Local-First Is a Data Boundary, Not a Safety Guarantee

Agent Island — Tue, 28 Jul 2026 01:19:02 +0000

A local AI coding tool can reduce data exposure, but the word local does not answer the questions a security review actually cares about.

The useful questions are narrower:

Which files can the agent read?
Which commands can it run?
Which network destinations can it reach?
Which credentials can it use?
What evidence reaches a reviewer before a change ships?

A process can run on a developer laptop and still have broad authority. It may scan an entire home directory, inherit shell credentials, call external services, or modify files outside the intended repository. Local execution is therefore a deployment property. It is not a complete safety model.

Start with four explicit boundaries

Before opening an agent session, write down four things: the readable files, writable files, permitted commands, and allowed external systems.

This sounds basic, but it changes the review from a vague question about whether a tool is trustworthy into a concrete question about what a particular session may do. A repository checkout plus unrestricted shell access is not a meaningful boundary. It is only local execution with wide authority.

Secrets deserve their own rule. Keep them out of prompts and transcripts. When a task genuinely requires a credential, use an existing scoped store or environment variable and separate read authority from write authority.

Keep observation local and bounded

Monitoring several coding agents does not require copying every transcript into a central service. A local companion can read the same session metadata already present on the machine and derive only the state needed for coordination: which session is active, waiting, blocked, or complete.

That observation layer still needs limits:

read only known provider directories;
cap file and record sizes;
tolerate partial writes;
avoid rendering secret-bearing transcript content;
retain compact derived state instead of duplicating raw logs.

This reduces both the data surface and the number of places that must be trusted.

Separate observation from execution

A status surface should not quietly become a remote-control surface. Seeing that a session needs attention does not mean the monitor should be able to type into that terminal, approve a command, merge a pull request, or deploy a release.

This separation matters because the monitoring process is long-lived. Giving it command authority turns a convenient dashboard into a high-value control plane. A safer design keeps observation read-only and moves every consequential action back to an explicit, reviewable workflow.

Treat evidence as part of the boundary

Local-first design does not remove the need for review. It changes what the reviewer should receive.

A useful handoff includes:

the requested outcome;
the files that changed;
the commands that ran;
the tests and checks that passed;
unresolved risks or skipped checks;
the exact decision still required from a human.

A completion message alone is not evidence. The reviewer needs enough information to reproduce the decision without reading an entire chat transcript.

Record incidents without centralizing everything

When something fails, preserve a compact incident record: session identity, time window, affected artifact, command category, observed failure, and recovery action. That is usually enough to diagnose recurring workflow problems without exporting full prompts or source code.

The goal is not zero telemetry. The goal is telemetry whose scope matches the operational question.

Local-first security is strongest when three boundaries line up: data stays where it should, authority remains narrow, and review evidence is sufficient. Missing any one of them leaves the workflow dependent on trust instead of controls.

The complete checklist is in the local-first AI coding security workflow.

Your Turn Is a Session Handoff, Not a Completion Claim

Agent Island — Mon, 27 Jul 2026 01:38:46 +0000

When a coding agent stops producing output, the next step is not automatically yours. It may be waiting on a tool, calculating, stalled, or actually finished. A useful your-turn state needs stronger evidence than silence.

The definition I use is narrow: your-turn means a specific Claude Code or Codex session has produced evidence that the next useful action belongs to the developer.

Process state and action ownership are separate

“Stopped” describes activity. “Your turn” describes ownership of the next step.

A semantic session event can support that handoff: an assistant message that asks a question, a structured approval prompt, or a completion event that explicitly returns control. File modification time, low CPU, and an unchanged process list are freshness clues, not proof of a handoff.

This distinction prevents two common errors:

calling a slow tool invocation finished;
calling an inactive but stalled process ready for the user.

When evidence is stale or ambiguous, the honest state is uncertainty.

The event must keep its session identity

Multi-session workflows make generic alerts almost useless. If three Codex sessions are open, “Codex needs you” still leaves the developer searching.

The handoff record should preserve the provider, project or thread identity, semantic event, and event time. Aggregation can rank a real your-turn state above passive working or stale state, but it must not erase the origin of the event.

If two sessions need attention, the UI should show both or apply a deterministic priority rule. A single generic badge is not enough.

An alert does not prove quality

Your-turn does not mean:

the implementation is correct;
tests passed;
the full task is complete;
the companion may approve or resume work automatically.

Those are separate verification and authorization questions. A status label should not smuggle them into a convenient notification.

Suppression and replay protection

Notification policy is part of the state model. When the exact target session is already frontmost, an extra sound may add no value. The visual state can remain while the sound is suppressed. If the developer switches away, the pending handoff must remain eligible for an alert.

The monitor must also deduplicate events. Re-reading the same local record after an app restart should not produce a second alert. Stable event identity, or a documented replay key, keeps one handoff equal to one notification.

A practical test

Start two sessions in different projects.
Leave one working and make the other ask a real question.
Confirm only the requesting session becomes your-turn.
Bring that session frontmost and inspect the alert policy.
Restart the monitor and verify the same event does not fire twice.
Answer the prompt and confirm new work clears the handoff state.

Agent Island v1.7.1 applies this model to Claude Code and Codex status on macOS and Windows. It reports the handoff; it does not silently operate the coding agent.

The canonical your-turn guide contains the full boundary and verification sequence.

An AI Coding Status Companion Should Observe, Not Operate

Agent Island — Mon, 27 Jul 2026 01:37:42 +0000

A coding agent can run for minutes without needing anything from you. The practical problem is not how to make it execute more work. It is how to leave the terminal, keep the right context, and return when the next action actually belongs to you.

That is the job of an AI coding status companion: a persistent desktop surface that observes session evidence and reports state without silently operating the agent.

Visibility and execution are different products

A runner decides what command or prompt comes next. A retry loop decides when to try again. A status companion has a narrower contract: show whether Claude Code or Codex is working, waiting, finished, or asking for attention.

That boundary matters. If a monitor also approves prompts or resumes tasks, its risk model changes. A visibility tool can stay useful without receiving authority over the workflow.

A state label needs evidence

A quiet terminal is ambiguous. The process may be calculating, blocked on a tool, stalled, or finished. File modification time and process activity help with freshness, but neither proves that the user owns the next step.

A stronger state model uses semantic events from the session record:

a recent tool event can support working;
an assistant message that requests input can support your turn;
a completion event can support finished;
stale evidence should remain uncertain rather than being promoted to a confident label.

The monitor also has to preserve session identity. “Codex needs you” is not enough when three Codex tasks are open. The alert must remain attached to the project or thread that produced it.

Notification policy is part of correctness

A your-turn alert is a handoff signal, not a claim that the implementation is correct. It does not prove tests passed or the task is complete.

It should also avoid duplicate noise. If the exact session is already frontmost, keeping the visual state while suppressing an extra sound can be reasonable. If the developer switches away, the pending handoff must remain visible. Re-reading the same event after an app restart must not fire a second alert.

Local-first needs an inspectable boundary

A desktop monitor may parse local session records. “Local-first” should mean the product names those records, limits what it reads, and does not upload session data by default. Sharing a report is a separate, explicit action.

Agent Island follows that boundary: no product account, no product telemetry, and no session-data upload to Agent Island.

A six-step evaluation

Run two sessions and check that the UI preserves both identities.
Make one session ask a real question.
Verify that only that session enters your-turn.
Leave a tool running and confirm silence is not called finished.
Restart the companion and check that the same handoff is not announced twice.
Disconnect the network and confirm local status observation still works.

Agent Island v1.7.1 is a free, open-source status companion for Claude Code and Codex on macOS and Windows. It provides visible state and your-turn alerts; it does not silently approve, resume, or operate either agent.

The full definition and verification checklist are available in the canonical guide.

A Weekly AI Coding Report Is an Activity Ledger, Not a Productivity Score

Agent Island — Sat, 25 Jul 2026 23:11:23 +0000

A week of Claude Code and Codex work leaves enough local evidence to answer concrete questions.

When were sessions active? Which provider produced the activity? Which models appeared? How did the token mix change by day?

It does not prove that the code was correct, the week was productive, or an API-value estimate was money spent.

That boundary is what makes a weekly report useful.

Use local calendar days

A readable report should cover today plus the previous six local calendar days. The headline, daily bars, provider totals, and model rows must use the same boundary.

If the chart uses calendar days but model rows use a rolling 168-hour window, the parts can disagree. A row may exceed the headline even though every individual calculation looks plausible.

Timezone and midnight behavior are accounting rules.

Token totals describe activity

Input, output, cache creation, and cache reads describe different work. I find it useful to keep two totals:

a wire-token total that includes every category recorded locally;
an input/output total that excludes cache traffic.

Neither is a productivity score.

A cache-heavy refactor can move more tokens than a small, high-impact fix. A failed run can be expensive. A quiet session can be waiting for a person instead of doing nothing.

Compare providers without inventing equivalence

A provider split can show how much recorded activity came from Claude Code and how much came from Codex. It cannot show that one token from each provider represents equal work, latency, quality, or quota pressure.

Provider quota is reported state. Local token activity is a reconstructed ledger. Displaying both is fine. Using one to fill missing data in the other is not.

Keep model context with each event

A session can switch models. A later token event needs the model context active at that time, not whichever model appears at the top of the file.

Unknown named models should stay visible and unpriced. Guessing a nearby model family makes historical reports impossible to audit.

Token rank and API-value rank are also different. A model with many inexpensive cache reads can lead by volume while another leads by estimated value.

My five-minute weekly review

I use the report as a prompt for one operational decision:

Check that all seven local days are present.
Look for gaps, replay spikes, or stale provider data.
Compare provider and model mix without treating either as quality.
Read estimated API value only under its displayed rate date.
Write one workflow change for next week.

That change might be reducing unattended runs, fixing a recurring authentication failure, or changing when I start a long session.

The number alone does not improve the workflow. The decision does.

Sharing must be a separate action

A local report should stay local by default. Agent Island builds its report from records already stored on the machine; transcript content is not uploaded to an Agent Island service.

A shareable card is a rendered summary, not an automatic broadcast. Copying or exporting it requires an explicit action. Before sharing, review visible dates, totals, model names, and project context for anything you do not want to disclose.

A weekly report earns trust by saying what each number means and what it cannot prove.

The complete workflow and current verified scope are in the canonical guide: AI coding weekly report.

An AI Coding Cost Tracker Needs a Measurement Contract

Agent Island — Sat, 25 Jul 2026 23:08:57 +0000

The most dangerous number in an AI coding dashboard is the one labeled cost without a definition.

A local tool can reconstruct token activity from Claude Code and Codex session records. It can apply a dated model-price table. That produces an estimate with a clear use: comparing periods and understanding the shape of local activity.

It does not produce an invoice.

Start at the file-format boundary

Claude Code and Codex do not write identical usage records. Claude can expose input, output, cache creation, and cache-read fields on assistant messages. Codex can separate model context from later token events, and cached input may be included inside total input.

Normalize those formats before calculating anything:

provider
timestamp
model
input tokens
output tokens
cache creation tokens
cache read tokens

Once that boundary exists, the rest of the report does not need to guess what a raw provider field means.

Cached input is not ordinary input twice

For a Codex event, a safe calculation starts by separating cached input:

non-cached input = max(total input - cached input, 0)

Then price non-cached input, output, cache creation, and cache reads with their own rates. Pricing total input and adding cache reads again creates a precise-looking overcount.

This is why a generic tokens * price function is not enough for a multi-provider tracker.

A rescan must not create new usage

Session files are read repeatedly. Apps restart. Watchers reconnect. Archived files can reappear. If the same event is counted every time it is observed, the weekly report grows while the underlying work stays unchanged.

Replay protection is part of accounting. Use stable provider event identifiers when they exist. If a format lacks one, document the fallback and its uncertainty instead of hiding it behind a polished total.

Date the price table

New model identifiers can appear before a desktop app knows their rates. API prices can also change.

A tracker should:

ship a dated rate snapshot;
keep unknown named models visible;
leave them unpriced rather than guessing a nearby rate;
preserve the rate date with historical reports.

In Agent Island, the calculated number is labeled API value. It is a counterfactual estimate under the embedded rates.

Keep four answers separate

A useful dashboard should not collapse these into one metric:

Provider quota: how close the account is to a reset boundary.
Local token volume: what the session records contain.
Estimated API value: a dated calculation over those token categories.
Actual billing: receipts, credits, subscriptions, and provider-side adjustments.

Only the fourth is a bill. The local records do not contain enough context to recreate it.

The evaluation checklist

Before trusting an AI coding cost tracker, ask:

Which exact local records does it read?
Does it separate input, output, cache creation, and cache reads?
How does it prevent replayed events from being counted twice?
What happens when a model is missing from the rate table?
Is the price snapshot dated?
Does the UI say estimate, or does it imply actual spend?
Is collection local, and is sharing a separate action?

The implementation can be sophisticated, but the contract should be easy to explain. If the number can be mistaken for money paid, the explanation belongs next to the number.

The full measurement contract and current Agent Island scope are in the canonical guide: AI coding cost tracker.