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.
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:
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.
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: