npm package: @robhowley/spinner-verbs
Description: Replace boring LLM spinner verbs with themes that have a little more personality.
Author: Rob Howley
Latest version: 2.1.2

# Spinner Verbs

> "Thinking..." is the most boring thing a genius could say.

Customize the text that appears while the LLM is working. Replace the default spinner verbs with something that has a little more personality.

**Before**: "Thinking...", "Processing...", "Working..." 🥱

**After**: "Paying the iron price...", "With fire and blood..." ⚔️🐉

## Choose Your Integration

- **Using [pi](https://pi.dev)?** → [Pi Integration](#pi-integration)
- **Using Claude Code?** → [Claude Code Integration](#claude-code-integration)
- **Browse themes** → [Available Themes](#available-themes)

---

## Pi Integration

If you use [pi](https://pi.dev), install this as a pi package directly from GitHub:

```shell
pi install npm:@robhowley/spinner-verbs
```

Or directly from GitHub:

```shell
pi install git:github.com/robhowley/spinner-verbs
```

That's it. The extension registers automatically and on the next session start will randomly pick a theme for you.

### Switching Themes with `/verbs`

Change your verb list at any time during a session:

```
/verbs game-of-thrones
/verbs doc-emrick
/verbs random
/verbs (default)
```

Run `/verbs` with no argument to get an interactive picker. Use `random` to pick a new random theme, or `(default)` to restore Claude's built-in spinner.

### Auto-configure via `settings.json`

Set your preferred theme once and forget about it. Pi checks both project-local (`.pi/settings.json`) and global (`~/.pi/agent/settings.json`) settings on session start.

**Randomly pick a theme each session (default):**

```json
{
  "spinnerVerbs": "random"
}
```

**Use a specific built-in theme by name:**

```json
{
  "spinnerVerbs": "game-of-thrones"
}
```

**Point to your own custom verbs file:**

```json
{
  "spinnerVerbsFile": "~/my-verbs.json"
}
```

The path supports three forms and is resolved relative to the `settings.json` file that contains it — not relative to your working directory:

| Form | Example | Resolved as |
|------|---------|-------------|
| `~/...` | `~/my-verbs.json` | Expanded from your home directory |
| `/absolute/...` | `/etc/my-verbs.json` | Used as-is |
| `relative/...` | `../my-verbs.json` | Relative to the `settings.json` file's directory |

So if your `.pi/settings.json` contains `"spinnerVerbsFile": "../my-verbs.json"`, it resolves to `my-verbs.json` in the project root — not wherever you launched pi from.

Your custom file can be a plain JSON array:

```json
["Brewing coffee...", "Asking the oracle...", "Consulting the void..."]
```

**Priority order**: `--verbs` CLI flag → project `.pi/settings.json` → global `~/.pi/agent/settings.json`

---

## Claude Code Integration

### Quick Start

Install any theme with a single command:

```shell
curl -sL https://raw.githubusercontent.com/robhowley/spinner-verbs/main/update-spinner-verbs.sh | bash -s game-of-thrones
```

Replace `game-of-thrones` with any theme name from the [`/spinner-verbs`](./spinner-verbs) directory.

### How It Works

The script will:
- Download the specified theme
- Create `.claude/settings.json` if it doesn't exist
- Merge the spinner verbs into your existing settings

### Manual Installation

Edit your Claude settings file directly:

```
~/.claude/settings.json            # global
[project-root]/.claude/settings.json  # project-specific
```

Add the spinner verbs configuration:

```json
{
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": [
      "Paying the iron price...",
      "What is dead may never die..."
    ]
  }
}
```

**Modes**:
- `"replace"` — swap out the defaults entirely
- `"append"` — add your verbs alongside the defaults

---

## Available Themes

| Theme | Sample                                                        |
|-------|---------------------------------------------------------------|
| `game-of-thrones` | Taking the black..., Winter is coming..., By your leave...    |
| `lord-of-the-rings` | One does not simply..., You shall not pass..." So it begins... |
| `action-movie` | Yippee-ki-yay..., I'll be back..., I know kung fu...          |
| `game-show` | Come on down..., Survey says..., Is that your final answer... |
| `doc-emrick` | Shunting..., Sliding..., Fiddling...                          |
| `momentum` | Making moves..., Spinning up..., Getting traction...          |

Use `"spinnerVerbs": "random"` to have a theme randomly selected from the list above at each session start.