pi-status-indicator

Claude Code-style status indicator for pi: a ping-ponging half-circle while working, a hand while waiting on you, a check when done, and a 2-4 word session theme in the header.

Packages

Package details

extension

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

npm repo home report

$ pi install npm:pi-status-indicator

Package: pi-status-indicator
Version: 0.1.1
Published: Sep 16, 2026
Downloads: 382/mo · 23/wk
Author: ramihmd
License: MIT
Types: extension
Size: 27.4 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

pi-status-indicator

A Claude Code-style status indicator for pi, in the terminal header and in pi's own working row:

alma-backend - π - ◐ - fix webhook retries     working, ping-ponging
alma-backend - π - ✋ - fix webhook retries     waiting on you
alma-backend - π - ✓ - fix webhook retries     done
alma-backend - π - fix webhook retries         idle

The last field is the session theme: two to four words naming what the session is about, generated once from your first prompt and stored as the session name, so /name and the session picker agree with the header.

Install

pi install npm:pi-status-indicator
pi -e /path/to/pi-status-indicator/index.ts   # try it without installing

Then /reload or restart pi.

Terminal.app

Terminal adds its own fields around the title — the working directory, the active process (that pi TERM_PROGRAM=… blob), and the window size. To see just the line above, open Terminal ▸ Settings ▸ Profiles ▸ Window and untick everything under Title (Working directory, Active process name, Dimensions, Shell command, Profile name).

Configure

/status-indicator                            show the current config
/status-indicator off                        hand the header back to pi, restore its indicator
/status-indicator on
/status-indicator frames ◐,◓,◑,◒            comma-separated frames
/status-indicator frames none                 no working animation (header keeps the theme)
/status-indicator interval 80                frame delay, 20-5000ms
/status-indicator waiting ✋ Hold on         the hand's label (header shows the first word)
/status-indicator done ✓ Finished
/status-indicator theme off                  stop naming sessions
/status-indicator theme model openrouter/deepseek-v4.1-flash
/status-indicator reset

Settings persist to ~/.pi/agent/pi-status-indicator/settings.json:

{
  "enabled": true,
  "frames": ["◐", "◓", "◑", "◒", "◑", "◓"],
  "intervalMs": 120,
  "labels": { "waiting": "✋ Waiting for you", "done": "✓ Done" },
  "naming": { "enabled": true, "model": "" }
}

Hand-edited files are safe: anything invalid falls back to the default, and an empty frames list means "no working animation".

The session theme

Once per session, after your first real prompt, the extension asks a model for a 2-4 word label and calls pi.setSessionName() with the answer. It skips slash commands, !bash, one-liners, and sessions you have already named by hand, and a failed call is silent — the header just keeps the shorter form.

naming.model empty means the session's own model. This is one extra model call per session with a ~600 character prompt; set a small model here if you run big ones by default, or turn it off.

How it works

Event	State
`session_start` / `session_shutdown`	idle, status cleared
`agent_start`	working — header animates, pi's working row shows the same frames
`ui_prompt_start`	waiting — hand in the header and footer, pi's working row hidden so it doesn't sit next to it
`ui_prompt_end`	back to what the state was before the prompt
`agent_settled`	done, until the next run
`session_info_changed`	repaint the header (renamed by `/name`, another extension, or the theme call)
`message_end` (first real user prompt)	name the session, once

Prior art

The pieces exist separately, and where they land is what differs here.

A spinner in the terminal title while the agent works: pi-status, pi-status-tab, and pi's own titlebar-spinner.ts example extension. None of them render a waiting or a done state.
Short LLM-generated session names: @nicknisi/pi-session-name, pi-session-name, @fyeeme/pi-session-name, @accolver/pi-status-bar, pi-spark. Nicknisi's also writes the title from a titleFormat template, but shows no indicator glyph.
Waiting-state awareness: @underactive/pi-topping and @tifan/pi-titlebar-spinner are the only two that also hook ui_prompt_start; the latter writes Herdr tab titles rather than Terminal's.

If you only want one of those pieces, install that package. This one is for the three-state sequence in the terminal title, with the session theme as the last field. Checked against 60 pi-packages on npm, 2026-09-16.

Not included

A preview picker for frames (/status-indicator frames is the escape hatch).
A custom working label: pi's own working message is left alone so the (esc to interrupt) hint stays intact. Use @underactive/pi-topping or @dustydonkey/pi-spinner if you want rotating verbs.

Development

npm test         # node --test, no build step
npm run typecheck

The state machine (src/state.ts), theme cleaning (src/naming.ts), and config parsing (src/settings.ts) are pure and tested without a pi runtime; tests/extension.test.ts drives the wiring against a stubbed extension API.

License

MIT