pi-shimmer-quotes-spinner ✨

Elegant animated spinner + rotating quotes for Pi coding agent. Merges Claude-style shimmer (✢ ✳ ✶ ✻ ✽), editable quotes, and full customisation — zero-config out of the box.

---

Features

Capability	Description
Shimmer Spinner	Ping-pong animation with · ✢ ✳ ✶ ✻ ✽ ✻ ✶ ✳ ✢ — same polished feel as Claude Code
Rotating Quotes	Display short, readable quotes alongside the working message — rotates at your chosen interval
Colour Sweep	Moving highlight band across the verb text (configurable on/off)
Token Counter	Live ↓ N tok counter with smooth display
Elapsed Timer	Appears after 15s alongside token info
Thinking State	Detects thinking phase and shows duration
Completion Toast	Brief ✻ Brewed for Ns when the agent finishes
Quote Modes	inline — quote on the same line as the verb; multiline — centred on its own line
Narrow Terminal	Automatically truncates quotes to fit available width
Editable Quotes	One-quote-per-line file, editable via /shimmer quotes edit
Hot-Reload Quotes	/shimmer quotes reload — no Pi restart needed
Fallback Quotes	25+ built-in quotes when no user file exists
5 Spinner Styles	shimmer, classic (braille), minimal (pulse dots), dots, braille (2-char)
3 Intensities	dim, normal, bright — verb & status colour brightness
No Conflicts	Spinner glyph + verb + status + quotes merged into one unified working message

---

Installation

# Via Pi (recommended)
pi install npm:pi-shimmer-quotes-spinner

# Or from GitHub
pi install git:github.com/<your-org>/pi-shimmer-quotes-spinner

# Restart Pi or /reload
/reload

Manual Install

mkdir -p ~/.pi/agent/extensions/pi-shimmer-quotes-spinner
cp -r src/* ~/.pi/agent/extensions/pi-shimmer-quotes-spinner/
/reload

---

Quick Start

No configuration needed. Once installed, Pi automatically shows:

✢ Brewing…  (↓ 127 tok · thinking)

With quotes enabled (default):

✢ Crafting…  (↓ 1,234 tok)  Simplicity is prerequisite for reliability. — Dijkstra

Or multiline:

✢ Crunching…  (↓ 3,678 tok · 32s)
    Simplicity is prerequisite for reliability. — Dijkstra

---

Commands

/shimmer                      Show current status and configuration
/shimmer style <name>         Switch spinner animation style
/shimmer speed <n>            Set animation speed (0.25 – 4.0)
/shimmer shimmer on|off       Toggle colour-sweep shimmer effect
/shimmer mode inline|multiline Set quote display layout
/shimmer interval <ms>        Set quote rotation interval (1000 – 60000 ms)
/shimmer intensity dim|normal|bright  Set verb/text brightness
/shimmer quotes reload        Reload quotes from disk immediately
/shimmer quotes edit          Open user quotes file in Pi's editor
/shimmer quotes path          Show the quotes file path
/shimmer on                   Enable the extension
/shimmer off                  Disable (restore Pi default)
/shimmer reset                Restore all default settings

Examples

# Switch to classic braille spinner
/shimmer style classic

# Speed up animation
/shimmer speed 2.0

# Dim the colours
/shimmer intensity dim

# Turn shimmer off but keep spinner
/shimmer shimmer off

# Show quotes in multiline centred mode
/shimmer mode multiline

# Rotate quotes every 5 seconds
/shimmer interval 5000

---

Configuration Reference

All settings are stored in ~/.pi/agent/pi-shimmer-quotes-spinner/config.json and persist across Pi restarts.

Field	Default	Description
spinnerStyle	"shimmer"	shimmer, classic, minimal, dots, braille
animationSpeed	1.0	Speed multiplier (0.25 – 4.0)
quoteMode	"inline"	inline or multiline
quoteInterval	8000	Quote rotation in milliseconds
quoteSource	"all"	user, bundled, or all
enableShimmer	true	Toggle colour-sweep effect
enableCustomSpinner	true	Use custom indicator frames
enableFallbackQuotes	true	Use built-in quotes as fallback
textIntensity	"normal"	dim, normal, bright
enabled	true	Master toggle

---

Custom Quotes

Create a quotes file at ~/.pi/agent/pi-shimmer-quotes-spinner/quotes.txt:

# One quote per line. Lines starting with # are ignored.
Simplicity is prerequisite for reliability. — Edsger W. Dijkstra
Programs must be written for people to read. — Harold Abelson
Talk is cheap. Show me the code. — Linus Torvalds

Or use the built-in editor:

/shimmer quotes edit

Changes are picked up automatically on the next agent run, or apply immediately:

/shimmer quotes reload

To see the file path:

/shimmer quotes path

---

Spinner Styles

Style	Frames	Look
shimmer	· ✢ ✳ ✶ ✻ ✽ ✻ ✶ ✳ ✢	Ping-pong Claude Code style
classic	⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏	Classic braille spinner
minimal	· • ● •	Gentle pulse
dots	⣀ ⣠ ⣴ ⣾ ⣿ ⣾ ⣴ ⣠	Braille block dots
braille	⠋⠙ ⠙⠸ ⠹⠴ ⠸⠦ ⠼⠧ ⠴⠇ ⠦⠏ ⠧⠋ ⠇⠙ ⠏⠹	Two-char braille

---

How It Works

The extension hooks into Pi's event system:

1. agent_start / turn_start — Picks a random verb, starts the shimmer timer and quote rotation timer
2. message_update — Tracks token count, thinking state, and elapsed time
3. setWorkingIndicator() — Drives the spinner glyph animation
4. setWorkingMessage() — Displays the combined verb + shimmer + status + quote
5. agent_end — Stops timers, shows ✻ Brewed for Ns notification
6. Quotes rotate on a separate timer independent of the shimmer tick

The spinner glyph, verb shimmer, status info, and quote are all merged into a single unified working message, avoiding conflicts between the three original package approaches.

---

File Structure

pi-shimmer-quotes-spinner/
├── package.json          # Pi package manifest
├── README.md             # This file
├── src/
│   ├── index.ts          # Extension entry — events & commands
│   ├── config.ts         # Configuration types, load, save
│   ├── spinner.ts        # Spinner frames, shimmer colour-sweep engine
│   ├── quotes.ts         # Quote loading, parsing, rotation
│   └── renderer.ts       # Builds the combined working message
└── examples/
    └── quotes.txt        # Example quotes file (copy to config dir)

---

Dependencies

• Peer: @earendil-works/pi-coding-agent >= 1.0.0
• Runtime: None (pure TypeScript, uses Pi's built-in APIs only)

---

License

MIT