NexusTerm — Reliable Activity Tracking for Coding Agents

The problem

When several coding agents work in terminals, their output is not the same as a useful operational picture. Which session just acted? What files did it touch? Is that activity happening now, or is the application replaying yesterday's transcript?

NexusTerm is my independent macOS terminal project. Its source connects terminal workspaces with transcript-backed tool activity, file tracking, and context indicators. The current build remains unfinished; this case documents a verified reliability slice, not a commercial release or customer outcome.

Two small defects with misleading consequences

The transcript watcher advanced its file offset after every read—even if the writer had only emitted half a JSON record. That could discard the incomplete record permanently. Splitting a multibyte character could also prevent the entire read from decoding.

Separately, the parser used the current clock for historical entries. Reading an old file could make an inactive session appear current, and token-growth samples reflected replay speed rather than recorded activity.

The repair

The watcher now commits its offset only through the last complete newline-delimited record. A partial suffix stays on disk for the next read, including a partially written Unicode character. Detectable truncation or file replacement resets the accumulated state; deletion clears the session. Repeated starts do not create duplicate watch streams.

The parser now uses the transcript's timestamp for activity, tool events, and token samples. Missing or invalid timestamps do not invent live activity.

Evidence and limits

The macOS Xcode app build and all 24 tests passed on September 6, 2026, including seven new transcript tests. Synthetic regression fixtures exercise every byte boundary of an emoji-containing record, repeated reads, malformed input, truncation, replacement, deletion, and historical/recent timestamps. A filesystem-notification test verified that a partial append stays unpublished until its terminating newline arrives. These fixtures do not contain private conversations or invoke a paid model.

This is not yet a recorded interactive dashboard demonstration. Same-directory session matching, duplicate usage records, large-file responsiveness, and recovery after dropped filesystem notifications still need work. Waiting states are heuristic. Static model-cost estimates are not billing-grade accounting.

The separate Swift-package build exposes existing Swift 6 concurrency errors; the successful Xcode build uses Swift 5 language mode. Neither a successful build nor these tests establishes release readiness.

Where the work transfers

For a team already using agents, a useful first engagement is one observable workflow: identify its session, expose meaningful activity, distinguish stale data, and test the failure cases. Agree on a baseline and acceptance checks before expanding the dashboard.

That is the value this project demonstrates: turning noisy agent output into information a person can assess, while being explicit about what remains uncertain.

Scope an AI systems review, compare engineering evidence, or describe the workflow you need to inspect.