Monitor Large Claude Code Transcript Archives Efficiently

Verified 2026-07-29. Claude Code writes append-oriented local records. A monitoring design can use that property to bound work while still preserving exact session identity and honest state transitions.

Why repeated full scans fail

Polling is not automatically expensive. The expensive pattern is reopening every transcript, reading a fixed tail from every file, parsing all of those tails, and repeating the work every few seconds even when almost nothing changed. Archive size then becomes part of the hot path.

This wastes CPU and I/O, but it also makes correctness harder. A partial tail can begin in the middle of a JSON line, an old completion event can be mistaken for the newest state, and simultaneous sessions can be collapsed into one global answer.

Separate discovery from ingestion

Run lightweight file discovery on its own cadence. Record stable identity, path, size, and modification time. Only files whose observable metadata changed should enter the parsing queue. A newly discovered file starts with a bounded bootstrap read; a known file resumes from its retained offset.

Keep an append-aware cursor

1. Store the last complete byte offset per transcript.
2. Read only the appended range when the file grows.
3. Carry an incomplete trailing line into the next read.
4. Reset safely when truncation or replacement is detected.
5. Persist the newest semantic evidence per exact session.

The cursor is an optimization only if recovery remains correct. A file identity change, smaller size, or invalid continuation should trigger a bounded re-bootstrap rather than silently skipping data.

Derive state from ordered evidence

Parsing fewer bytes does not justify weaker semantics. Keep provider and session identity, compare timestamps, and distinguish working, waiting, your-turn, error, finished, and stale evidence. Silence is a freshness signal, not proof that a run completed successfully.

Measure the monitor itself

Track files inspected, bytes read, parse failures, queue depth, and scan duration. Test with an archive large enough to expose accidental O(n) polling. The expected steady state is proportional to changed files and appended bytes, not total history.

Where Agent Island fits

Agent Island v1.7.1 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. It is a visibility layer, not an execution or approval system.