@nicknisi/pi-sidepulse
Report pi agent status to SidePulse LEDs: working, waiting for input, done
Package details
Install @nicknisi/pi-sidepulse from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@nicknisi/pi-sidepulse- Package
@nicknisi/pi-sidepulse- Version
0.1.2- Published
- Nov 19, 2026
- Downloads
- 519/mo · 519/wk
- Author
- nicknisi
- License
- MIT
- Types
- extension
- Size
- 13.6 KB
- Dependencies
- 0 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@nicknisi/pi-sidepulse
Makes SidePulse LEDs follow pi sessions the same way the SidePulse installer's built-in hooks follow Claude Code, Codex, Cursor, Junie and Grok. SidePulse ships no pi hook, so without this pi runs never show up on the device or in the SidePulse menu bar.
What it adds
No commands, tools, widgets or entry types. It listens to pi lifecycle events and reports each pi session to the SidePulse background service with sidepulse report:
| pi event | SidePulse state | LEDs |
|---|---|---|
session_start |
idle |
— |
agent_start |
working |
cyan |
ui_prompt_start |
blocked (--kind permission for confirm, question otherwise; prompt title as --msg) |
amber |
ui_prompt_end |
back to the state before the prompt | |
agent_settled |
done, or idle when the run was aborted |
green |
session_shutdown |
clear (removes the session) |
Each pi session reports under its own scope, pi-<sessionId>, with app pi and the session name (or the cwd's folder name) as its title, so it gets its own row in the SidePulse menu bar and sidepulse status. ui_prompt_* covers every ctx.ui prompt, so any extension dialog (for example ask_user_question or a permission confirm) lights the device amber.
Requirements
- The SidePulse software installed with
curl -fsSL https://sidepulse.io/setup.sh | sh, which puts the CLI at~/.local/bin/sidepulseand runs the background service. - pi ≥ 1.1 (
agent_settledwithaborted,ui_prompt_*events).
Configuration
None. The CLI path is fixed to ~/.local/bin/sidepulse, the installer's default.
Caveats
- Best-effort. Reports are spawned in order and never block pi; on shutdown pi waits at most 0.5s for the final
clear. If the CLI is missing or the background service is down, they fail silently. - UI sessions only. Runs without a UI (
pi -p, JSON mode) don't report, so one-shot scripts don't leave stale sessions behind. Interactive (TUI) and RPC sessions both report, since RPC hosts can showctx.uiprompts too, so SDK/RPC embeddings get their own SidePulse rows. - Killed sessions. If pi is killed instead of quitting cleanly (for example, the terminal is closed),
clearmay not be sent. The SidePulse service expires old sessions on its own. - Each report starts a short-lived
sidepulseprocess (about 0.1s on an M-series Mac), a handful per prompt. - Depends on the SidePulse
reportCLI interface (--scope,--state,--app,--title,--kind,--msg), documented in SidePulse's program status protocol.
Install
pi install /Users/nicknisi/Developer/pi-extensions/packages/sidepulse