Skip to content

PRESENCE.md

Latest commit

 

History

History
70 lines (50 loc) · 1.9 KB

PRESENCE.md

File metadata and controls

70 lines (50 loc) · 1.9 KB

Presence

Termlings presence is terminal-first and file-backed.

What presence means

  • online: Agent session exists in .termlings/store/sessions/<sessionId>.json.
  • typing/working: Agent has recent terminal activity written to .termlings/store/presence/<sessionId>.typing.json with source: "terminal".

Source of truth

  • Launcher PTY activity writes typing state.
  • No Claude hook runtime path is used.
  • Session heartbeats keep lastSeenAt fresh.

Presence file

{
  "typing": true,
  "source": "terminal",
  "updatedAt": 1708952400000
}

Path:

  • .termlings/store/presence/<sessionId>.typing.json

Detection model

  • Presence is armed by real submit/input events and internal injected message writes.
  • Output-only redraw noise (including resize repaint) is suppressed/disarmed.
  • Typing auto-clears after idle timeout.
  • Sending a message clears sender typing immediately.
  • Consumers also suppress typing briefly right after message timestamps to avoid races.

Freshness windows

  • Session staleness: old sessions are removed after stale threshold.
  • Typing staleness: old typing state is ignored after stale threshold.
  • Message-based suppression: typing is temporarily suppressed right after message send.

UI behavior

  • TUI: avatar strip animates while typing/working, message pane footer shows animated dots.
  • Web: avatars can render talking state from typing/working presence.

Troubleshooting

If presence appears stuck or noisy:

  1. Restart active agent sessions so latest launcher logic is loaded.
  2. Watch typing files: 
    tail -f .termlings/store/presence/*.typing.json
  3. Confirm sessions: 
    ls .termlings/store/sessions
  4. Remove stale runtime files if needed: 
    rm -f .termlings/store/sessions/*.json
rm -f .termlings/store/presence/*.typing.json

Legacy hooks

Termlings no longer uses hooks for live presence.