Context
An agent (Claude Code harness) coordinating in a room wanted live notifications of room messages and stick movements while doing other work — the harness has a Monitor facility where each stdout line from a script becomes a notification. There is no documented way to do this with tt, so the agent improvised a poll loop over tt events <path> --json --limit 50, tracking event_seq itself.
What happened
The first call (no --after) replayed history starting from the agent's stored join cursor rather than from "now" — dozens of stale events (in this case everything since seq 15494 while the room head was ~15612) flooded the notification stream before the watcher caught up.
Underlying gaps
- No documented watch pattern. The bundled instructions (
tt instructions show) explain wait/release/handoff discipline but say nothing about how to watch a room live: when to use tt msg recv --wait (single-shot) vs recv --follow vs tt events --follow vs tt standby --wake cmux, what the output framing of --follow is (one JSON object per line?), and how each interacts with the stored cursor.
- No cheap way to learn the current head sequence to seed
--after. tt status --json does not expose it; the workaround is fetching a batch and taking max(event_seq).
--limit N returns the N oldest events since the cursor, not the newest — tt events --limit 1 surprisingly returns the oldest pending event. There is no --tail N / --latest.- Replay-from-cursor as the default is right for turn catch-up (
tt wait) but surprising for a fresh watcher; --follow beginning at "now" (with --after as the opt-in catch-up) would match tail -f expectations.
Suggested fixes
- Document a recommended live-watch idiom in the bundled harness instructions (including the no-replay incantation and
--follow framing).
- Expose the room head sequence in
tt status --json (or add tt events --head).
- Add
--tail N (or --since now) to tt events/tt msg recv.
- Make
--follow with no --after start at the current head.
Environment
tt 0.14.1, macOS (darwin 27), Claude Code harness, room with 5 active agents.
Context
An agent (Claude Code harness) coordinating in a room wanted live notifications of room messages and stick movements while doing other work — the harness has a Monitor facility where each stdout line from a script becomes a notification. There is no documented way to do this with
tt, so the agent improvised a poll loop overtt events <path> --json --limit 50, trackingevent_seqitself.What happened
The first call (no
--after) replayed history starting from the agent's stored join cursor rather than from "now" — dozens of stale events (in this case everything since seq 15494 while the room head was ~15612) flooded the notification stream before the watcher caught up.Underlying gaps
tt instructions show) explain wait/release/handoff discipline but say nothing about how to watch a room live: when to usett msg recv --wait(single-shot) vsrecv --followvstt events --followvstt standby --wake cmux, what the output framing of--followis (one JSON object per line?), and how each interacts with the stored cursor.--after.tt status --jsondoes not expose it; the workaround is fetching a batch and takingmax(event_seq).--limit Nreturns the N oldest events since the cursor, not the newest —tt events --limit 1surprisingly returns the oldest pending event. There is no--tail N/--latest.tt wait) but surprising for a fresh watcher;--followbeginning at "now" (with--afteras the opt-in catch-up) would matchtail -fexpectations.Suggested fixes
--followframing).tt status --json(or addtt events --head).--tail N(or--since now) tott events/tt msg recv.--followwith no--afterstart at the current head.Environment
tt 0.14.1, macOS (darwin 27), Claude Code harness, room with 5 active agents.