@scpz24/pi-breath

pi-breath is a one-line semantic activity stripe for the Pi Coding Agent TUI. It replaces Pi's built-in Working row while an Agent is active and communicates requesting, thinking, writing, tool categories, compaction, continuation/rate limiting, and errors through color breathing and short deterministic glitches.

The stripe is deliberately small: it is a non-capturing Overlay at viewport row 0, owns one deadline-driven timer only while visible, and disappears completely once the Agent is settled and its FIFO transition effects have finished.

flowchart LR
  Hooks["Pi public hooks"] --> State["Fact state + priority selector"]
  State --> Timeline["Dwell / crossfade / breath / glitch"]
  Timeline --> Stripe["One-line Overlay"]

Install

Install the package with Pi's package command:

pi install npm:@scpz24/pi-breath

Minimum verified host version: Pi 0.84.1. The package declares @earendil-works/pi-coding-agent and @earendil-works/pi-tui as host-provided peers and ships TypeScript source for Pi to load directly.

To avoid showing two activity indicators, use Pi 0.84.1's actual settings path:

{
  "terminal": {
    "showTerminalProgress": false
  }
}

Commands

/pi-breath
/pi-breath status
/pi-breath off
/pi-breath on

off applies only to the current session: it immediately removes the stripe, stops its timer, clears pending visual transients, and restores Pi's built-in Working indicator. Hooks continue tracking facts at zero timer cost, so on can recover the current Agent/tool/stream phase. No command writes persistent configuration or sends a message to the model.

Stable frames use a continuous upper-half-block (▀) track with no horizontally moving beam. The whole semantic color breathes over 1800ms at a 50ms supplement cadence (20 FPS); ingress, egress, and error events temporarily introduce deterministic accent, dim, and short-gap segments at their own discrete keyframes.

When NO_COLOR is present, the renderer emits no RGB foreground or background sequences. It expresses breathing and glitches using dim, normal, bold, and short gaps.

Known limitations

• Pi's Overlay API is public but marked experimental, so future Pi versions may require compatibility updates.
• The terminal background is queried only after the first lazy Overlay factory provides the public TUI instance. The first frame uses the dark palette; query failure or the 200ms timeout quietly keeps that palette.
• Turn the stripe off or let it become idle before switching between Pi's regular and fullscreen renderers. An Overlay entry does not migrate between live TUI instances.
• If the required public Overlay or Working APIs are absent, or Overlay creation fails, the extension safely degrades, restores built-in Working, and notifies once. /pi-breath on explicitly retries.

Development

Run from the monorepo root:

npm --workspace @scpz24/pi-breath run typecheck
npm --workspace @scpz24/pi-breath test
npm --workspace @scpz24/pi-breath run build

The package has no runtime dependency on @scpz24/pi-worktree-hud; each extension remains independently installable and releasable. The full product contract is in docs/pi-breath.md.