ashxj-spinners

A pi coding-agent extension that drives the working-indicator row with state-specific spinner pools and per-state kaomoji. The row is just ${spinner} ${kaomoji} — no text.

Status: active development. Spinner pool choices and kaomoji are being iterated on.

What it looks like

The row that appears during streaming becomes:

[spinner] [kaomoji]

With a spinner picked at random from the state's pool on entry, plus the kaomoji re-rolled every 30 s during long states, so a long thinking stretch cycles through faces instead of freezing on one. Examples:

thinking:    ⢁⠂⠔⠈ (ᵕ—ᴗ—)
searching:   ⠁⠀    (⸝⸝⩌ ⤙ ⩌⸝⸝)
editing:     ⡀⠀⠀  (ᵕ • ᴗ •)
toolRunning: ⣀⣀   (๑´>᎑<)~
error:       ⠀⠶⠀  (,,>﹏<,,)

idle, startup, and complete are truly silent — no spinner, no kaomoji, no text. The row is blank during rest.

The state machine

The extension subscribes to pi's lifecycle events and picks a (spinner, kaomoji) pair for the current state:

State	Spinner pool	Kaomoji pool	Triggered by	Silent?
idle	—	—	session_start, agent_end with no assistant reply	yes
startup	—	—	session_start with reason: "startup"	yes
thinking	shared pool (6 spinners)	shared pool (14 kaomoji)	turn_start	no
searching	diagswipe scan cascade	2 kaomoji	tool_execution_start matching the search regex	no
editing	columns fillsweep	3 kaomoji	tool_execution_start matching the edit regex	no
toolRunning	shared pool (6 spinners)	shared pool (14 kaomoji)	tool_execution_start (default)	no
complete	—	—	agent_end with stopReason ∈ {stop, length}	yes
error	pulse	6 kaomoji	tool_execution_end with isError, or agent_end with stopReason ∈ {error, aborted}	no

thinking and toolRunning share one pool. Both states draw their spinner and kaomoji from the same combined pool (6 spinners, 14 kaomoji), so they're visually interchangeable. The shared spinner pool is rain breathe checkerboard sparkle braille snake. The other states keep their own pools.

Kaomoji re-roll within a state. While an active state is showing, the kaomoji is re-rolled every KAOMOJI_REROLL_MS (30 s) so a long state cycles through faces instead of freezing on one. The spinner is not re-rolled on this timer (restarting its animation would stutter); it only changes on state transitions.

Minimum state TTL (3 s)

The TTL prevents flicker between active states — notably, turn_start firing immediately after an error won't clobber the error before the user can see it. The TTL only applies to active→active transitions:

• Active → active: TTL-gated. If within 3 s, the new state is rejected.
• Active → silent (idle / startup / complete): TTL bypassed. These are end-of-turn markers and must always be reachable, otherwise the spinner would get stuck in an active state when the LLM finishes a turn within 3 s of starting.
• Active → error: TTL bypassed. Error has priority and can always be set.
• Tool execution start: TTL bypassed via force: true. When a tool starts, the spinner changes to the tool state immediately so it syncs with the tool bubble. Without this, a tool starting within 3 s of turn_start would leave the spinner stuck on the thinking spinner while the tool bubble is already on screen.
• Silent → active: TTL bypassed (silent states aren't in STATES_WITH_TTL).
• Auto-revert timers (e.g. complete → idle after 3 s) bypass the TTL by calling doApplyState directly.

Spinners

Spinners are powered by the unicode-animations npm package. See SPINNERS.md for the per-state pool list, plus instructions for adding or swapping spinners. thinking and toolRunning share one combined spinner pool (see above).

Installation

From a local path (for development)

In ~/.pi/agent/settings.json:

{
  "extensions": [
    "/path/to/extensions/ashxj-spinners"
  ]
}

Then /reload inside pi.

From npm (published)

pi install npm:ashxj-spinners

Or add it to ~/.pi/agent/settings.json:

{
  "packages": ["npm:ashxj-spinners"]
}

See the pi packages gallery and package docs for more.

Customization

Everything lives in index.ts as a single file. Common edits:

Want to…	Edit
Add or remove a spinner from a state's pool	the matching entry in SPINNER_POOL_FOR_STATE
Change the kaomoji pool for a state	the matching entry in KAOMOJI_FOR_STATE
Change the shared thinking/toolRunning spinner pool	THINKING_TOOL_SPINNER_POOL
Change the shared thinking/toolRunning kaomoji pool	THINKING_TOOL_KAOMOJI_POOL
Change how often the kaomoji re-rolls within a state	KAOMOJI_REROLL_MS
Add a new state	extend the State union, add to SPINNER_POOL_FOR_STATE and KAOMOJI_FOR_STATE, call applyState(...) from a new event handler
Change the auto-revert delay for complete / startup	TRANSIENT_MS
Change the minimum state TTL	STATE_TTL_MS
Color the spinner or kaomoji differently	the ctx.ui.theme.fg(...) calls in doApplyState

Compatibility

• pi coding-agent 0.80+ (uses ctx.ui.setWorkingIndicator() and ctx.ui.setWorkingMessage())
• Terminal: any modern terminal with Unicode support. Tested primarily in VS Code's integrated terminal.

License

MIT — see LICENSE.