From 3.42.0 every running session can report itself, not only the ones holding a claim, so a view of who is working shows a session that is reviewing, waiting on tests or waiting for its person. The plugin contacts no tracker for this: it runs one command your repository names, and what a report means, where it is stored and when it expires are up to that command.

Key Shape Default Purpose
presence.command string absent: nothing runs Your repository's own command, run from the repository root through the shell for at most 20 seconds, never on the hook's own clock. An absent or null block, or a blank command, runs nothing and writes nothing.
presence.intervalMinutes integer, 1 to 60 5 How often a small per-session keeper reports while the session's Claude Code process lives. A value out of range reads as 5, and doctor warns.

The command runs at session start (PRESENCE_EVENT=start, state starting); on a prompt (beat, working, when a minute or more has passed since the last report; start when the session has not reported yet or has ended); on a tool use while the session is starting or waiting (beat, working); when a turn finishes and Claude waits for its person (beat, waiting); from the keeper every interval (beat, the latest state); and at session end (end, ended, with PRESENCE_END_REASON such as clear). When the keeper finds the session's process gone it reports end with reason gone. Pressing Esc fires no hook, so the keeper notices the interrupt itself and reports waiting; from 3.61.1 that includes an Esc pressed while the model is still thinking, before any reply text appears, which it reads from Claude Code's own status file for the session, so the session shows as waiting for its person within seconds rather than later looking stalled. A state change within 30 seconds of the last report is held and carried by the next one. The command receives PRESENCE_EVENT, PRESENCE_STATE, PRESENCE_SESSION_ID, PRESENCE_MACHINE, PRESENCE_CHECKOUT, PRESENCE_BRANCH, PRESENCE_ITEM (an item number the branch name carries as its own segment, else empty), PRESENCE_PLUGIN_VERSION, PRESENCE_INTERVAL_MINUTES, PRESENCE_END_REASON (on end only), PRESENCE_AT (when the report was queued, epoch milliseconds), PRESENCE_ACTIVE_AT (from 3.44.0, the session's last activity, epoch milliseconds), CLAUDE_CODE_SESSION_ID and CLAUDE_PID.

Rules your implementation should keep:

  • Display only. Presence never decides who acts; claims do. It may renew or release claims its own session holds.
  • Expire on the server. A machine that sleeps or loses power sends no end, so a report not renewed within a few intervals means the session is gone.
  • Alive is not active. A hung turn still beats. A working report whose PRESENCE_ACTIVE_AT is long past is hung, or in one long command, because activity is stamped after a tool use, not before.
  • Fail fast and quietly, and quote every variable: a branch name can hold shell syntax.

Presence is separate from activeAgents, which marks plan roots during build runs only. The contract is skills/setup/references/session-presence.md in the plugin repository.