pi-working-vibe

Custom Working… message and tool-aware spinner for pi.

Replace pi's default ⠋ Working… with themed flavor text that rotates while the agent is thinking, and automatically switches when the model calls a tool. Ships with four ready-to-use vibes: mafia, hacker, pirate, zen.

⠋ The Don is stirring...                        (default thinking)
⠙ The boys are kicking down doors...            (when calling bash)
⠹ The ledger is being scanned...                (when calling read)
⠸ The contract is being amended...              (when calling edit)

Install

# From npm (recommended)
pi install npm:pi-working-vibe

# From GitHub (always latest main)
pi install git:github.com/Davidcreador/pi-working-vibe

# Project-local (writes to .pi/settings.json instead of global)
pi install -l npm:pi-working-vibe

# Try without installing (single-run, ephemeral)
pi -e npm:pi-working-vibe

That's it. Default vibe (mafia) activates immediately on the next session.

Update later with pi update npm:pi-working-vibe. Remove with pi remove npm:pi-working-vibe.

What it does

• Rotating message: picks random lines from vibes/<name>.txt every ~3.5s while pi is in a turn.
• Tool-aware: switches to a tool-specific pool the instant the model invokes bash, read, edit, grep, find, ls, write, web_search, web_fetch, todo, or any custom tool you've authored a section for.
• Customizable spinner: swap the ⠋⠙⠹⠸ glyphs for one of six presets (dots, line, pulse, braille, arrow) or fully custom frames, with a themeable color.
• Safe: atomic settings writes, path-traversal guards, mtime-cached file IO, file-size caps, graceful degradation when a vibe pool is missing.

Vibe file format

Vibes are plain text. One message per line. # for comments. Optional [section] headers split lines into named pools:

# mafia.txt
The Don is stirring...
Shadows tally the books...

[tool:bash]
The boys are kicking down doors...
A package is being delivered...

[tool:read]
The ledger is being scanned...

[tool:edit]
The contract is being amended...

Pools fall back to [default] when the active tool doesn't have its own section. A file with no headers becomes one big default pool (backward compatible with any flat vibe file).

Customize your own vibe

Drop a .txt file into ~/.pi/agent/vibes/ and switch to it:

# in pi
/vibe list                  # shows installed vibes (bundled + user)
/vibe vibe:hacker           # switch
/vibe info                  # current settings + line counts
/vibe pools                 # sections in the active vibe
/vibe preview               # show a sample line

User files in ~/.pi/agent/vibes/ override bundled files of the same name, so you can fork mafia.txt without losing the package update.

/vibe command reference

| Form | Effect | |---|---| | /vibe | Toggle master switch | | /vibe info | Show active settings + line counts | | /vibe list | List installed vibes (user + bundled) | | /vibe pools | List sections in the active vibe | | /vibe on | /vibe off | Enable / disable | | /vibe reload | Re-read settings + vibe file from disk | | /vibe preview | Pick a sample line from the active pool | | /vibe vibe:<name> | Switch active vibe | | /vibe indicator:<preset> | default | dots | line | pulse | braille | arrow | custom | | /vibe color:<token> | Theme color for spinner (e.g. accent, primary, dim) | | /vibe rotate:<ms> | Message rotation interval (0 = no rotation) | | /vibe interval:<ms> | Spinner frame interval |

Settings reference

All keys live at the top level of settings.json. Project file <cwd>/.pi/settings.json overrides global ~/.pi/agent/settings.json.

| Key | Type | Default | Effect | |---|---|---|---| | workingVibe | boolean | true | Master switch | | workingVibeName | string | "mafia" | Vibe file name (no .txt) | | workingVibeRotateMs | number | 3500 | Rotation interval; 0 = static. Floor 750ms | | workingIndicator | enum | "default" | Spinner preset | | workingIndicatorColor | string | "accent" | Theme color token | | workingIndicatorFrames | string[] | [] | Custom frames (when workingIndicator: "custom") | | workingIndicatorIntervalMs | number | 90 | Spinner frame interval. Floor 40ms |

Legacy: a string value workingVibe: "<name>" from earlier ad-hoc usage is auto-migrated to {workingVibe: true, workingVibeName: "<name>"} on first load.

Lifecycle (how it hooks into pi)

session_start         → load settings, install indicator, build picker
agent_start           → reset state, set message, start rotation timer
tool_call             → activePool=tool:<name>, refresh message
tool_execution_end    → if no more active tools, back to default
message_start (asst.) → snap to a fresh line as model resumes talking
agent_end             → stop rotation, reset state
session_shutdown      → tear down timer + null out ctx ref

Built on the extension API patterns: setWorkingMessage, setWorkingIndicator, and the tool_call / tool_execution_end event pair.

Authoring tips

• Pi only renders the working line during the streaming/tool phase. Compaction and retry loaders keep their own built-in styling — this is a pi constraint.
• Custom frames are rendered verbatim; colors come from pi's theme.
• Parallel tool calls: the most-recently-started tool wins. When that tool ends, the pool falls back to the next most-recent surviving tool, or to default if there are none.
• Edit a .txt file while pi is running — mtime caching auto-invalidates on the next read, or run /vibe reload.

Bundled vibes

| File | Theme | |---|---| | mafia.txt | 1930s mob / made-men / consigliere | | hacker.txt | 90s cyberpunk / phreakers / ICE | | pirate.txt | High seas / treasure / plunder | | zen.txt | Calm / contemplative / minimalist |

Each ships with ~110–140 lines across 11 sections (default + 10 tool pools).

Contributing

PRs welcome — especially new vibe themes. Each vibe should cover the standard tool taxonomy (bash, read, edit, write, grep, find, ls, web_search, web_fetch, todo) plus a meaty [default] pool.

License

MIT