# 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.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Pi Package](https://img.shields.io/badge/pi-package-blue)](https://pi.dev)

---

## 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

```bash
# 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

```bash
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

```bash
# 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`:

```text
# 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