# @zerosnow/pi-shimmer

Gentle per-character color sweep for pi's working message (vibes).

`pi-shimmer` transparently wraps `ctx.ui.setWorkingMessage` to intercept plain-text
messages set by other extensions (like `pi-powerline-footer`'s AI-generated vibes)
and applies a moving highlight-band animation across the text.

> Inspired by the shimmer implementation in `@dustydonkey/pi-spinner`.

<p align="center">
  <img src="assets/shimmer-demo.gif" alt="pi-shimmer demo" width="500">
</p>

## Features

- **Transparent monkey-patch** — no changes needed in other extensions
- **6 built-in color presets** + `auto` (follows theme accent)
- **Idle-aware** — pauses shimmer when the agent is waiting (no flicker)
- **Lightweight** — configurable interval, per-character ANSI RGB coloring

## Install

```bash
pi install npm:@zerosnow/pi-shimmer
```

## Usage

The extension activates automatically on session start. Configure it via the
`/shimmer` command, or by editing your settings files:

- **Global** (all projects): `~/.pi/agent/settings.json` (pi's standard location)
- **Project** (overrides global): `.pi/settings.json` in your project root

### Commands

```
/shimmer                    Show current preset (and where it takes effect)
/shimmer <preset>           Switch preset (auto|gold|silver|rose|neon|rainbow|off)
/shimmer speed <ms>         Set animation interval (default 200, min 50)
/shimmer band <width>       Set highlight band width (default 4, range 1-10)

Append `--global` (or `-g`) anywhere to save to the **global** settings file
instead of the current project, e.g.:

```
/shimmer --global gold
/shimmer speed 150 -g
/shimmer band 3 --global
```

Without the flag, config is written to the current project's `.pi/settings.json`
(which overrides global). If the project file can't be written, the command
reports an error instead of silently dropping the change.
```

### Settings

```jsonc
// ~/.pi/agent/settings.json (global) or .pi/settings.json (per-project)
{
  "workingVibeShimmer": "auto"              // string shorthand
  // or full object:
  "workingVibeShimmer": {
    "preset": "gold",
    "speed": 150,
    "bandWidth": 3
  }
}
```

Config is merged like pi settings: **project overrides global**, global overrides
defaults. Fields are merged individually, so you can override just one field
(e.g. project sets only `"preset"` while the global `speed`/`bandWidth` remain).

> ⚠️ Global config lives in `~/.pi/agent/settings.json` (pi's standard
> location), **not** `~/.pi/settings.json`. The latter is not read by pi.

## Presets

| Preset  | Base                  | Shimmer            |
|---------|-----------------------|--------------------|
| `auto`  | theme accent          | lightened accent   |
| `gold`  | dark gold (184,134,11)| bright gold        |
| `silver`| grey (128,128,128)    | light silver       |
| `rose`  | muted rose            | warm rose          |
| `neon`  | teal (10,138,138)     | cyan (0,255,255)   |
| `rainbow` | rolling neon marquee | seven rainbow hues  |
| `off`   | — (disabled)          | —                  |

## License

MIT