Reading Claude Code Transcript JSONL as Ordered Evidence

A transcript reader fails long before it encounters invalid JSON. The more common failure is semantic: a valid Claude Code event looks like completion, but it actually belongs to a sidechain, carries an API error, or has already been superseded by the next user turn.

That changes the job from parsing lines to reducing ordered evidence.

The envelope is the compatibility boundary

Claude Code stores one JSON object per line. Read the file incrementally because the last record may still be in flight. A blank, malformed, or partial line should be skipped for the current pass and reconsidered after the next append.

The state projection can remain small:

• type and uuid for event kind and identity
• timestamp for semantic ordering
• message.stop_reason and toolEndsTurn for completion candidates
• isSidechain for background context
• isApiErrorMessage for failure classification

A missing field should preserve uncertainty. It should not activate a fallback that happens to look good in the UI.

File time and event time answer different questions

A modification timestamp tells you that the transcript container changed. It does not identify the turn represented by each object. Once a session has several turns, ordering by file time collapses different events into one moment.

Use the timestamp carried by the event and preserve stable identity. Then allow later user or start activity to supersede an earlier completion candidate.

Filter the two most expensive false positives

The first is a sidechain finish. A background subagent can complete while the parent is still working. It may belong in diagnostics, but it is not automatically a foreground your-turn alert.

The second is an error wrapped like assistant output. A rate limit or API failure needs an error state, not a success state. isApiErrorMessage must be checked before generic completion reduction.

A conservative reducer

A useful state reducer can be described in five rules:

1. Keep scanning after a malformed record.
2. Order events by their own semantic timestamps.
3. Remove sidechain finishes from foreground handoff candidates.
4. Route provider errors before generic completion.
5. Accept completion only if no later event invalidates it.

This is why grep-based monitors age poorly. A word match cannot prove identity, order, context, or success.

Privacy needs an equally conservative sentence

Agent Island reads these records on the device and does not upload transcript content to an Agent Island service. That claim does not say every historical and future Claude Code transcript has the same schema. The reader still needs version-aware tests and an explicit unknown state.

The canonical field guide includes the complete ordering model and released scope.