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