What Should a Claude Code Status Companion Actually Do?

A Claude Code status companion is useful when the terminal is no longer the window you are watching. Its job is not to replace Claude Code. It is to preserve enough local session state that you can answer one question from elsewhere: does this run still need time, or does it need me?

That sounds simple until a tool treats every new transcript line as progress, every quiet file as completion, or every completion-shaped event as permission to alert. A reliable companion needs a stricter contract.

1. Reconstruct state, not just activity

Claude Code writes local session records as work progresses. A monitor can observe those records, but a recent write alone does not say what happened. The useful states are semantic: working, waiting for the user, completed, rate-limited, authentication required, network failure, or stale and unknown.

Agent Island reads local records and refreshes status without uploading transcript content to an Agent Island service. It preserves provider and session identity so a state change still points back to the run that produced it. Old activity expires instead of being displayed forever as fresh work.

2. Alert on a handoff, not on every finish event

A completion event can belong to the foreground session, a background worker, or an internal subagent. Only some of those moments require a human reply. A useful your-turn alert checks the session identity and the latest meaningful event before interrupting.

Agent Island can show a foreground alert and notification when a background Claude Code turn needs attention. On macOS, the verified focus-aware behavior can hold the alert while the relevant session is already visible and re-evaluate after focus changes. The product does not claim that every completion event deserves a sound.

3. Keep the data boundary understandable

A local status tool should be explicit about its inputs. Agent Island reads the session data Claude Code already stores on the machine. No Agent Island account is required, and there is no Agent Island product telemetry. Session data is not uploaded to an Agent Island service.

This boundary is narrower than saying a computer never reaches the network. Claude Code itself remains a provider service, and optional provider-reported usage windows use the credentials already present on the machine. The status companion does not become a new transcript cloud.

4. Separate shared behavior from platform-specific proof

Agent Island v1.7.1 is publicly available for macOS and Windows. The shared verified foundation is live Claude Code and Codex status, local monitoring, and your-turn alerts. macOS uses a native SwiftUI menu-bar or notch surface. Windows uses a native WPF floating top bar.

The newer usage, cost, report-card, and visual-personalisation surfaces described elsewhere have current real-device verification on macOS. This page does not infer Windows parity for those surfaces from a successful build alone.

5. Know what the companion does not do

• It does not automatically resume a Claude Code run.
• It does not send transcript content to an Agent Island account.
• It does not turn an estimated API value into a billing claim.
• It does not treat a stale file timestamp as proof that work is still running.
• It does not promise identical unverified behavior on macOS and Windows.

A six-question evaluation checklist

1. Can the tool distinguish working, your-turn, error, and stale states?
2. Does an alert retain the exact provider and session identity?
3. Can a background completion avoid impersonating a user handoff?
4. Does the documentation say which files or provider surfaces are read?
5. Are macOS and Windows claims backed by separate evidence?
6. Does the tool stop at visibility instead of silently triggering more work?

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.