pi-presence

Ambient session-status for the pi coding agent: per-session state files, self-labeling terminal tabs, and a menubar/TUI view of every session (needs-you / running / dormant).

Packages

Package details

extension

Install pi-presence from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:pi-presence
Package
pi-presence
Version
0.2.0
Published
Jul 20, 2026
Downloads
286/mo · 286/wk
Author
devnav
License
MIT
Types
extension
Size
50 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./extensions/index.ts"
  ],
  "image": "https://raw.githubusercontent.com/navbytes/pi-presence/main/assets/demo.png"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-presence

Ambient session-status for the pi coding agent. This extension gives every pi session a live status — needs-you / running / idle / dormant — by writing a small state file on each transition and self-labeling its terminal tab, so a menu-bar or TUI reader can show every session at a glance.

npm license: MIT

pi-presence-watch grouping pi sessions by needs-you / running / idle / dormant.

Install

pi install npm:pi-presence

Requires pi ≥ 0.78.1 (live-tested on 0.79.2). No build step — pi loads the shipped TypeScript with jiti. On your next session start you get a self-labeling tab and a state file at <agentDir>/live/<session-id>.json.

What it does

  • State files. Atomically writes working / blocked / idle per session on every transition, with a terminal-correlation snapshot for click-to-focus.
  • Self-labeling tabs. Sets the tab title via pi's ctx.ui.setTitle where available, falling back to a guarded, sanitized OSC write (tui + TTY only) on older pi versions.
  • Needs-you. Consumes the cooperative herdr:blocked event (ref-counted), so it interoperates with herdr and any extension that raises the same event.
  • Permission gate (optional). A bundled producer that raises herdr:blocked around a confirmation for risky shell commands. Enable with "extensions": ["./extensions/index.ts", "+permission-gate/index.ts"].
  • Notifications (optional). Desktop alerts on blocked and long-run-finished transitions (macOS).

Settings (settings.json → pi-presence)

Key Default Meaning
enabled true Master switch.
title true Self-label the terminal tab (TUI only).
titleFormat "{icon} {name} · {state}" Placeholders: {icon} {name} {state} {cwd} {branch}.
notify false Desktop notifications.
idleDebounceMs 250 Debounce after agent_end before settling to idle.
retryGraceMs 2500 Re-check delay when a settle fires but the agent isn't idle yet.
notifyThresholdMs 10000 Min working time before a "finished" notification.

A trusted project's .pi/settings.json overrides these per key; a mistyped value falls back to its default with a one-line stderr warning.

See the repository README for the full state schema, the reader CLI, and the verified herdr:blocked contract.

License

MIT