What Should a Codex Status Companion Actually Track?

A Codex run can keep working after you leave the terminal, but the useful question is not simply whether a process exists. You need to know which session changed, whether it is still producing work, whether it is waiting for you, and whether a provider error has replaced normal progress.

A status companion can answer those questions from local evidence. It should not turn gaps in that evidence into fictional precision.

1. Keep each Codex session distinct

Codex session records contain events that belong to a particular run. A monitor needs stable identity, semantic event time, and replay protection. Scanning the same archived record twice must not produce two completions or double the token ledger.

Agent Island reads supported local session records, keeps Codex separate from Claude Code, and uses the latest meaningful event to derive visible state. A stale session expires to an unknown state instead of appearing permanently active.

2. Treat your-turn as a state transition

A finish-shaped event does not always mean a person must return. Background work and internal agent activity can finish without creating a user handoff. A useful alert requires an exact session and evidence that the next meaningful action belongs to the user.

Agent Island can surface that transition with a compact status change, a notification, and a foreground alert. It does not automatically resume the Codex session or trigger another prompt. Visibility remains separate from execution authority.

3. Show the current weekly window, not the retired one

In the verified July 2026 provider state, Codex exposes a weekly quota window. It does not expose the old five-hour window. A correct Codex companion therefore shows one weekly reset window rather than preserving a stale two-tile layout.

The weekly percentage is useful for capacity planning. It is not a token counter, an invoice, or proof that every local event was captured.

4. Keep local token activity and estimated value separate

On macOS, Agent Island v1.7.1 can parse local Codex token events into a ledger and apply a dated price table to known model identifiers. Unknown models remain unpriced. The result is an estimated API-equivalent value, not a claim about subscription spend or money saved.

Reconciliation with a provider billing surface would require a controlled experiment with matching windows, model identifiers, included usage, and complete provider-side accounting. A status companion should label that uncertainty instead of hiding it.

5. Make the local boundary explicit

Agent Island does not require an account and does not upload transcript content to an Agent Island service. Status and ledger calculations use records already on the device. Optional provider usage refreshes use the existing local provider credentials; they do not create an Agent Island transcript backend.

6. Verify each platform independently

Agent Island v1.7.1 ships for macOS and Windows. The shared verified scope is live Claude Code and Codex status, local monitoring, and your-turn alerts. macOS uses native SwiftUI; Windows uses native WPF.

The Codex weekly usage, local cost ledger, report cards, and visual-personalisation behavior discussed here has current real-device verification on macOS. This reference does not claim those newer surfaces are verified on Windows.

A six-question evaluation checklist

1. Does the tool retain exact Codex session identity?
2. Can it distinguish a real handoff from background completion?
3. Does it show one current weekly window rather than a retired five-hour window?
4. Are replayed token events deduplicated?
5. Is estimated API value clearly separated from billing?
6. Are macOS and Windows claims supported independently?

Current release scope

This reference was verified against the public Agent Island v1.7.1 release on 2026-07-25. The release is neither a draft nor a prerelease and includes a macOS DMG and a Windows x64 ZIP. Agent Island is free and MIT licensed.