pi-spinner-lyrics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jamieeeeeeeee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# pi-spinner-lyrics
+
+A [pi](https://pi.dev) extension that retires the agent's beige, focus-grouped spinner verbs and replaces them with rotating phrases drawn from the catalog of Phish — cycled every ~2.5s, shimmered Claude-style, and crowned with a waxing-and-waning moon in place of the default braille spinner.
+
+## Tired of boooooring corpo spinner verbs?
+
+Let's be honest: "Thinking…", "Working…", "Processing…" — the stock spinner verbs of every LLM tool are not Fun. They do not let you show off your discerning personality from within your LLM configuration.
+
+Lucky for you there is always Phish: a polarizing four-piece from Vermont who, across forty years and a catalog north of three hundred originals, have built a body of work that polite music critics have variously described as *eccentric*, *labyrinthine*, and — in one infamous 1997 review of their August 10 show at Deer Creek Music Center — a band that "could urinate in its fans' ears and tell them it's music," with said fans dutifully "there with tape recorders to capture the moment." Detractors call the lyrics nonsense. Phans are there for something that feels slightly akin to summer camp songs — the lyrics are always a little weird, but at this point it's tradition and part of the lore. Either way, the material is uncommonly rich in vivid, oddly-specific gerunds — the exact grammatical shape a spinner verb wants to be — and there is, mercifully, a *lot* of it.
+
+This extension mines that repertoire for inline-verb gold. Whether you are a hater who thinks it all sounds like bee-bee-beep-boop-beee-bee-boop-doop-a-loo, or someone with 300 shows under your belt, you will find these prompts measurably more entertaining than the standard corpo verbs. The catalog is deep enough that you will not see the same phrase twice in a working session, and weird enough that you may briefly forget you were waiting on a model at all.
+
+Is it useful? Define "useful". Is it better than the OEM spinner? Unambiguously yes.
+
+## What you actually get
+
+- A rotating list of short verb-phrases inspired by the Phish songbook, refreshed every ~2.5 seconds while the agent is working.
+- A Claude-style shimmer that sweeps a bright highlight left-to-right across each phrase using your active pi theme's color ramp.
+- A moon-phase emoji indicator (🌑🌒🌓🌔🌕🌖🌗🌘) cycling every 120ms in place of the default braille spinner.
+- Phrases grouped in source comments by song so you can blame, credit, or argue with the curator.
+- Zero runtime dependencies beyond pi itself.
+
+## Install
+
+```bash
+pi install git:github.com/jamieeeeeeeee/pi-spinner-lyrics
+```
+
+Or try it without installing:
+
+```bash
+pi -e git:github.com/jamieeeeeeeee/pi-spinner-lyrics
+```
+
+## What it does
+
+Listens for `agent_start` / `turn_start` and cycles `ui.setWorkingMessage(...)` with a random verb from a hand-curated list of Phish lyrics. Restores the default message on `agent_end` / `session_shutdown`.
+
+## License
+
+MIT

package/extensions/constants.ts

@@ -0,0 +1,284 @@
+// Tunables and Phish-lyric verbs used by the spinner-lyrics extension.
+// Adjust the constants below to tune timing, spinner glyphs, and the
+// shimmer highlight without touching the extension logic.
+
+// How often to swap to a new random verb, in milliseconds.
+export const VERB_INTERVAL_MS = 2500;
+
+// How often to repaint the shimmer highlight, in milliseconds.
+export const SHIMMER_INTERVAL_MS = 80;
+
+// Moon-phase frames replace pi's default braille spinner.
+export const MOON_FRAMES = ["🌑", "🌒", "🌓", "🌔", "🌕", "🌖", "🌗", "🌘"];
+export const MOON_INTERVAL_MS = 120;
+
+// How far the bright "head" travels per shimmer tick, in characters.
+export const SHIMMER_STEP = 1;
+
+// Width of the falloff on each side of the head (in characters).
+// Beyond this distance the character renders as "dim".
+export const FALLOFF = 3;
+
+export type ThemeColor = "accent" | "text" | "muted" | "dim";
+
+// Map distance-from-head → theme color name. Index 0 = head.
+export const RAMP: ThemeColor[] = ["accent", "text", "muted", "dim"];
+
+// Phish-lyric verbs used by the spinner-lyrics extension.
+// Grouped by song where known; some are unattributed.
+export const VERBS: string[] = [
+  // "Roses Are Free" (Ween cover, frequently played by Phish)
+  "Taking a piece of tinsel",
+  "Putting it on the tree",
+  "Cutting a slice of melon",
+  "Carving out a pumpkin",
+  "Relying on your destiny",
+  "Getting in your car and cruising the land of the brave and free",
+  "Understanding exactly what you put on the tree",
+  "Disbelieving the florist when he tells you that the roses are free",
+  "Taking a wrinkled raisin",
+  "Pushing it into third",
+  "Eating plenty of lasagna",
+  "Resisting all the urges that make you wanna go out and kill",
+  "Throwing that pumpkin at the tree",
+  "Believing that pumpkin holds your destiny",
+  "Casting it off into the sea",
+  "Baking that pie and eating it with me",
+
+  // "Run Like an Antelope"
+  "Setting the gearshift",
+  "Running like an antelope out of control",
+
+  // "Reba"
+  "Sinking a boulder in the water",
+  "Tying a cable to a tree",
+  "Stirring it with the ladle that Grandmother bought her",
+  "Bagging it, tagging it, selling it to the butcher in the store",
+  "Dipping the ladle for a taste of her creation",
+  "Hearing the never-ending coral maze",
+  "Wiping primal soup from my shoes",
+  "Stuffing a newt into my sack",
+  "Scraping musty grime off with Rick's fork",
+
+  // "Bouncing Around the Room"
+  "Bouncing around the room",
+
+  // "Harry Hood"
+  "Taking care of my shoes",
+  "Feeling good about Hood",
+  "Thanking Mr. Miner",
+  "Wandering soaking, secretly afraid",
+
+  // "Sample in a Jar"
+  "Wheeling around because I didn't hear",
+  "Helping you to your car",
+  "Letting the binding belt enclose me",
+  "Dancing with Elihu up on Leemor's bed",
+  "Letting the market stands unfold",
+  "Unheeding all the times I raise my cup",
+
+  // "Free"
+  "Floating in the blimp a lot",
+  "Swimming weightless in the womb",
+  "Splashing in the sea",
+
+  // "Golgi Apparatus"
+  "Looking into the finance box",
+  "Looking into the microscope",
+  "Seeing the Golgi Apparatus",
+  "Running like a junkyard dog with a brain of brass",
+  "Seeing you with a ticket stub in your hand",
+
+  // "Mike's Song" / "Weekapaug Groove"
+  "Sharing in a Weekapaug groove",
+  "Trying to make a woman that you move",
+  "Walking through the hallways inside my mind",
+  "Chasing the backbeat falling behind",
+
+  // "Wading in the Velvet Sea"
+  "Taking a moment from my day",
+  "Wrapping it up in things you say",
+  "Mailing it off to your address",
+  "Wading in the velvet sea",
+
+  // "Chalk Dust Torture"
+  "Climbing up my waterfalls and swinging on my vines",
+  "Stealing all my lines",
+  "Collecting chalk dust on my tongue",
+
+  // "Slave to the Traffic Light"
+  "Plugging the distress tube up tight",
+  "Slaving to the traffic light",
+
+  // "Limb by Limb"
+  "Leaning on a shoulder carved out of stone",
+  "Coming unglued while in mid-air",
+  "Never wanting my hand cut off",
+  "Never wanting a hacking cough",
+  "Taking the best parts back",
+  "Landing to reform limb by limb",
+  "Peeling my fingers off the rim",
+  "Turning left",
+  "Pooling like water that drips from above",
+  "Being trampled by lambs",
+  "Tossing with the salad",
+
+  // "Maze"
+  "Stumbling as I fall from Grace",
+  "Seeing what I'm hunting a few steps away",
+  "Taking a wrong turn on the wrong path",
+  "Sweeping into the cavern of shame and the hall of dismay",
+  "Never getting out of this maze",
+
+  // "Esther"
+  "Making soup for the ambassadors",
+  "Singing to the troubadours",
+
+  // "Bathtub Gin"
+  "Making bathtub gin",
+  "Taking a bath, because we're all in this together",
+
+  // "Stash"
+  "Pulling the pavement from under my nails",
+  "Brushing past a garden, dependent on whales",
+  "Yanking on my tunic",
+  "Dangling my stash",
+  "Zipping through the forest with the curdling fleas",
+  "Seizing the mutant",
+  "Crying to my cohorts",
+  "Bed-heating the apple toast",
+  "Watching the solar garlic start to rot",
+  "Poking a double decker on a llama, taboot",
+
+  // "Ghost"
+  "Telling you the story of the ghost",
+  "Feeling forsaken",
+  "Leaving the latch left unhooked",
+  "Waiting in the wind and rain",
+  "Calling the ghost instead",
+
+  // "Birds of a Feather"
+  "Flocking outside like birds of a feather",
+  "Pecking at the ground and strutting out of stride",
+
+  // "Tweezer"
+  "Stepping into the freezer",
+  "Teasing her with a tweezer",
+
+  // "Fluffhead"
+  "Asking the banker for some powerful pills",
+
+  // "Possum"
+  "Coming from atop the mountain where the people come to pray",
+  "Engraving words on the walls of the cave",
+
+  // "Punch You in the Eye"
+  "Paddling 'til I could take no more",
+  "Punching you in the eye",
+  "Tying you to a chair with a giant clip",
+  "Laying this hate on you",
+
+  // "I Didn't Know"
+  "Disliking cheeseburger alleycats",
+  "Inquiring about the picture of Otis Redding taken just before he died",
+  "Breaking my sunny shoe shine",
+  "Greeting mustard pies and carrot eyes",
+
+  // "The Lizards"
+  "Meeting an aging knight in the corridor",
+  "Surrendering to the flow",
+  "Remembering all the thoughts that he had thunk",
+  "Realizing the lizards, they have died",
+
+  // (Phish — source unconfirmed)
+  "Bouncing like a newborn elf",
+  "Sleeping the sleep of death",
+
+  // "Esther" (the doll's flight) (?)
+  "Floating higher over hills and valleys and treetops",
+  "Tumbling and diving through the clouds",
+  "Plummeting earthward",
+
+  // "The Squirming Coil"
+  "Watching Satan catch a ray on the beach",
+  "Licking the coil some day",
+  "Stunning the puppy",
+  "Burning the whale",
+
+  // "Cavern"
+  "Forging the coin and licking the stamp",
+  "Putting your money where your mouth is",
+
+  // (Phish — source unconfirmed; possibly "Foam")
+  "Running so fast my feet don't touch the ground",
+  "Falling into a deep well through the foam",
+
+  // "Backwards Down the Number Line"
+  "Blowing out candles once again",
+  "Whispering it into his ear",
+
+  // "46 Days"
+  "Waiting 46 days for the coal to run out",
+  "Tasting the fear, for the devil's drawing near",
+
+  // "The Lizards"
+  "Wondering if tigers sleep in lily patches",
+
+  // "Tube"
+  "Living in this tube, so stupendous",
+  "Biding my time and taking it slow",
+
+  // "The Divided Sky"
+  "Watching the sky divide",
+
+  // "You Enjoy Myself"
+  "Washing Uffizi",
+  "Driving me to Firenze",
+
+  // "Split Open and Melt"
+  "Tossing it in my carryall",
+  "Running the wide load to the lip",
+  "Watching the big core crack and glow",
+  "Splitting open and melting",
+  "Bumping my head and raising a welt",
+  "Coming apart at the seams",
+  "Breathing in a steam dream",
+  "Plunging below the water line",
+
+  // "Fee"
+  "Using a bamboo cane to help keep the pace",
+  "Racing with the wind",
+  "Flirting with death",
+  "Hopping and jumping in wooden shoes",
+  "Finding Fee and Millie on a lover's trek",
+  "Trying to stay with Millie",
+  "Getting bottled upside the head",
+  "Slamming him in a face with a nectarine",
+  "Slicing him on the nipple",
+
+  // "Harpua"
+  "Coming to your town",
+  "Helping you party down",
+  "Mourning Poster Nutbag",
+
+  // "Cities" (Talking Heads cover, frequently played by Phish)
+  "Finding myself a city to live in",
+  "Looking over at the dry ice factory",
+
+  // "It's Ice"
+  "Mimicking the image",
+  "Pressing on the elastic sheet",
+  "Breathing through a slice",
+
+  // Dog-Faced Boy
+  "Sparing a moment for the dog-faced boy",
+  "Lending another hand to the worm girl",
+  "Depleting your oxygen",
+
+  // Piper
+  "Waking up Piper, the red, red worm",
+
+  // Dirt
+  "Living beneath the dirt",
+  "Being free from push and shove",
+];

package/extensions/spinner-lyrics.ts

@@ -0,0 +1,131 @@
+// Spinner Lyrics: replaces pi's spinner verb with rotating Phish-lyric verbs,
+// rendered with a Claude-style shimmer (a moving bright highlight sweeping
+// left→right across the text).
+//
+// Behavior:
+// - While the agent is streaming/working, cycles a random verb every ~2.5s.
+// - Between verb changes, repaints the working message every ~80ms with a
+//   shimmer highlight that travels across the text, then wraps and repeats.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  VERBS,
+  VERB_INTERVAL_MS,
+  SHIMMER_INTERVAL_MS,
+  MOON_FRAMES,
+  MOON_INTERVAL_MS,
+  SHIMMER_STEP,
+  FALLOFF,
+  RAMP,
+  type ThemeColor,
+} from "./constants";
+
+type Theme = { fg(color: string, text: string): string };
+type WorkingIndicator = { frames: string[]; intervalMs?: number };
+type WorkingUi = {
+  setWorkingMessage(msg?: string): void;
+  setWorkingIndicator?(spec?: WorkingIndicator): void;
+  theme?: Theme;
+};
+
+function colorAt(distance: number): ThemeColor {
+  if (distance < 0) distance = -distance;
+  if (distance >= RAMP.length) return "dim";
+  return RAMP[distance]!;
+}
+
+function shimmer(text: string, head: number, theme: Theme | undefined): string {
+  if (!theme) return text;
+  let out = "";
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+    if (ch === " ") {
+      // Spaces have no visible glyph; skip styling to avoid pointless escapes.
+      out += ch;
+      continue;
+    }
+    const d = Math.abs(i - head);
+    out += theme.fg(colorAt(d), ch);
+  }
+  return out;
+}
+
+export default function (pi: ExtensionAPI) {
+  let verbTimer: NodeJS.Timeout | undefined;
+  let shimmerTimer: NodeJS.Timeout | undefined;
+  let lastUi: WorkingUi | undefined;
+  let lastIdx = -1;
+  let currentVerb = "";
+  let head = -FALLOFF; // start off-screen left so the highlight glides in
+
+  function pickVerb(): string {
+    if (VERBS.length === 0) return "Working";
+    if (VERBS.length === 1) return VERBS[0]!;
+    let i = Math.floor(Math.random() * VERBS.length);
+    if (i === lastIdx) i = (i + 1) % VERBS.length;
+    lastIdx = i;
+    return VERBS[i]!;
+  }
+
+  function paint() {
+    if (!lastUi) return;
+    const text = `${currentVerb}…`;
+    lastUi.setWorkingMessage(shimmer(text, head, lastUi.theme));
+    head += SHIMMER_STEP;
+    // Reset once the head has fully traversed the text plus its trailing falloff.
+    if (head > text.length + FALLOFF) head = -FALLOFF;
+  }
+
+  function rotate() {
+    currentVerb = pickVerb();
+    head = -FALLOFF;
+    paint();
+  }
+
+  function start(ui: WorkingUi) {
+    lastUi = ui;
+    ui.setWorkingIndicator?.({ frames: MOON_FRAMES, intervalMs: MOON_INTERVAL_MS });
+    if (!verbTimer) {
+      rotate();
+      verbTimer = setInterval(rotate, VERB_INTERVAL_MS);
+    }
+    if (!shimmerTimer) {
+      shimmerTimer = setInterval(paint, SHIMMER_INTERVAL_MS);
+    }
+  }
+
+  function stop() {
+    if (verbTimer) {
+      clearInterval(verbTimer);
+      verbTimer = undefined;
+    }
+    if (shimmerTimer) {
+      clearInterval(shimmerTimer);
+      shimmerTimer = undefined;
+    }
+    if (lastUi) {
+      lastUi.setWorkingMessage(); // restore default
+      lastUi.setWorkingIndicator?.(); // restore default spinner
+      lastUi = undefined;
+    }
+  }
+
+  pi.on("agent_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    start(ctx.ui as unknown as WorkingUi);
+  });
+
+  pi.on("turn_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    // Re-arm in case the previous turn's tool execution cleared it.
+    start(ctx.ui as unknown as WorkingUi);
+  });
+
+  pi.on("agent_end", async () => {
+    stop();
+  });
+
+  pi.on("session_shutdown", async () => {
+    stop();
+  });
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "pi-spinner-lyrics",
+  "version": "0.1.0",
+  "description": "Replaces pi's spinner verb with rotating Phish-lyric verbs.",
+  "keywords": ["pi-package", "pi-extension", "spinner", "phish"],
+  "author": "jamieeeeeeeee",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamieeeeeeeee/pi-spinner-lyrics.git"
+  },
+  "pi": {
+    "extensions": ["./extensions/spinner-lyrics.ts"],
+    "image": "https://i.ytimg.com/vi/o0F-NmSkPBM/hqdefault.jpg"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}