pi-thinking-shimmer

Configurable working spinner for Pi — selectable default or Claude glyphs, theme-aware colors, shimmer, thinking glow, token count, stall detection, and layered verb lists.

Fork attribution: This package is derived from ouzhenkun/pi-claude-shimmer, licensed MIT. The original spinner implementation and verb lists remain attributed to ouzhenkun; this fork adds layered configuration. See LICENSE.

Why

Pi's built-in working indicator is functional but minimal. pi-thinking-shimmer adds a polished, configurable shimmer experience to your Pi sessions:

• Verb shimmer — The verb text has a moving color sweep (shimmer), with different speed and direction depending on whether Pi is sending a request or receiving a response
• Thinking timer — Detects when the model is thinking, shows a glowing "thinking" label with a sine-wave shimmer (3s delay, like Claude Code), then transitions to "thought for Ns"
• Token count — Live ↓ N tokens with smooth counter animation (no jumps)
• Elapsed time — Appears after 30s alongside the thinking/token status
• Stall detection — After 3s without new tokens, the verb smoothly transitions to red via color interpolation (not a hard binary switch)
• Tool-use flash — When tools are executing, the entire verb text oscillates between base and shimmer colors (sine wave)
• Spinner ping-pong — The spinner characters animate forward then backward (· ✢ ✳ ✶ ✻ ✽ ✻ ✶ ✳ ✢), matching Claude Code's animation
• Completion notification — Shows a brief ✻ Brewed for Ns notification when the agent finishes

Install

pi install npm:pi-thinking-shimmer

Or install this local fork during development:

pi install /home/jadelclemens/code/pi-thinking-shimmer

Usage

No configuration is required—the extension works automatically once installed. To customize its working and completion verbs, create any of these files (searched in this order):

1. <cwd>/.pi/pi-thinking-shimmer/config.json
2. <project-root>/.pi/pi-thinking-shimmer/config.json (the nearest ancestor with .git)
3. ~/.pi/agent/pi-thinking-shimmer/config.json

Set root-level "searchUp": true in any of those regular config files to also load .pi/pi-thinking-shimmer/config.json from every parent of the CWD through $HOME. Regular locations are resolved first, so a project or global setting can enable the search. Parent configs are loaded nearest-first; a parent with "searchUp": false is included and then stops the parent search. Paths outside $HOME are never searched. This is useful for a shared ~/code/.pi/pi-thinking-shimmer/config.json without turning ~/code into a Git repository.

Each file may configure its working verbs, completion verbs, and multiline tips independently:

{
  "searchUp": true,
  "verbs": {
    "mode": "append",
    "items": ["Gitting Gud", "Scheming"]
  },
  "completionVerbs": {
    "mode": "replace",
    "items": ["Got gud", "Schemed"]
  },
  "glyphs": "default",
  "colors": {
    "verb": "accent",
    "shimmer": "warning",
    "glyph": "accent",
    "muted": "dim",
    "thinking": "thinkingText",
    "stall": "#b53b4b"
  },
  "tips": {
    "mode": "replace",
    "items": [
      "Try not being so bad at programming next time!",
      "Do it yourself, meatbag!"
    ],
    "interval": { "min": 4, "max": 6 },
    "keep": { "min": 1, "max": 2 },
    "prefix": "Tip: ",
    "enableShimmer": true,
    "enabled": true
  }
}

Glyph and color options

glyphs defaults to "claude", which uses the existing ping-pong Claude-style glyph animation. Set it to "default" to restore Pi's built-in spinner glyphs.

colors defaults to "claude", retaining the original orange/gray palette. Alternatively, set colors to an object. Every color role accepts a Pi theme foreground color (such as "accent", "warning", "dim", or "thinkingText") or a custom #RGB/#RRGGBB value. Omitted roles retain their Claude-palette fallback. The roles are verb, shimmer, glyph, muted, tip, tipShimmer, thinking, thinkingShimmer, and stall.

mode defaults to "append". Configurations are read from CWD to global: each append is retained, then the first replace stops the search. The resulting list is built from that replace upward, so a CWD append extends a project replace. With no replace, configured entries append to the built-in list. An empty replace list disables that type of verb (and suppresses the completion notification for completionVerbs). Tips use the same rule, but have no bundled defaults.

Tips always render left-aligned on the line below the spinner. prefix defaults to an empty string and is concatenated directly before the selected tip—no separator or extra space is inserted, so include any desired trailing space in the prefix itself (for example, "Tip: "). They are scheduled by spinner-verb redisplays rather than elapsed time: keep is the number of consecutive redisplays for which the chosen tip remains visible, and interval begins only after that tip's final visible redisplay. The next tip begins on the intervalth subsequent redisplay—there are therefore interval - 1 fully tip-free redisplays between tips. Each accepts either an integer or { "min": integer, "max": integer }, inclusive; the latter selects a random value for each schedule. Defaults are interval: 8 and keep: 3. For example, interval: { "min": 4, "max": 6 }, keep: { "min": 1, "max": 2 } displays a random tip for one or two redisplays after a random four-to-six-redisplay post-tip interval. enableShimmer controls only the tip text, leaving the verb shimmer unchanged; enabled: false hides tips without disabling the spinner. Invalid or missing settings are ignored.

Publishing

.forgejo/workflows/publish.yml runs on a vX.Y.Z tag, checks that the tag is reachable from main, typechecks, verifies that the tag matches package.json, and publishes to npm. Once Forgejo is available, add an npm automation token as the repository Actions secret NPM_TOKEN, configure the repository's origin remote, then push a matching tag—for example v1.0.6.

States

· Building…                                     ← requesting (no status yet)
✢ Crafting…  (thinking with high effort)        ← thinking (< 3s, no glow)
✳ Crafting…  (↓ 127 tokens · thinking)          ← thinking with tokens
✶ Cooking…   (↓ 1,234 tokens)                   ← responding (< 30s)
✻ Crunching… (32s · ↓ 3,678 tokens)             ← responding after 30s
✽ Brewing…   (1m 3s · ↓ 4,567 tokens)           ← tool-use (flash animation)
✻ Crunched for 2m 5s                            ← completion (notify)

Features at a Glance

Feature	Description
Verb shimmer	Moving color sweep on verb text
Request/respond arrows	↑ when sending, ↓ when receiving
Thinking glow	Sine-wave shimmer on "thinking" text after 3s
Token counter	Smooth animated ↓ N tokens
Elapsed timer	Duration shown after 30s
Tool-use flash	Verb oscillates between colors during tool execution
Stall detection	Verb smoothly transitions to red after 3s without tokens
Spinner ping-pong	Characters animate forward then backward
Completion notify	Past-tense verb notification on finish

Dependencies

• @earendil-works/pi-coding-agent (peer)

License

MIT. This fork also adapts the multiline quote/tip renderer from yoyo406/pi-shimmer-quotes-spinner, whose npm package metadata declares MIT. The upstream source artifact shipped an invalid LICENSE file, so this fork preserves yoyo406's attribution and an MIT notice in LICENSE.