claude-spin-class

Learn while Claude thinks.

A small CLI that swaps the Claude Code spinner verbs for something worth reading — Spanish vocab, HTTP status codes, Oscar winners, periodic table elements, collective nouns, and more. Every time Claude is working, you're passively picking something up.

⠋ 403 → Forbidden: auth won't help
⠙ A shrewdness of apes
⠹ ¿Cuánto cuesta? (How much does it cost?)
⠸ ⌘⇧P → Command Palette

It just writes to ~/.claude/settings.json. That's the whole trick.

Example with claude-spin-class spanish

---

Install

npm install -g claude-spin-class

Or without installing:

npx claude-spin-class spanish

Requires Node ≥ 18 and Claude Code.

Usage

claude-spin-class <theme>             # set a theme
claude-spin-class random [category]  # pick something at random
claude-spin-class list [category]    # see what's available
claude-spin-class --help

The theme persists in ~/.claude/settings.json until you change it.

Themes

Tech

Theme	Subtypes	Entries
http	1xx 2xx 3xx 4xx 5xx	33
vscode	navigation editing search	62
terminal	navigation history power	54
regex	anchors character-classes quantifiers groups patterns	51
bigo	concepts sorting searching data-structures	44

Languages

Theme	Subtypes	Entries
spanish	greetings verbs travel food sports numbers time	175
french	greetings verbs travel food numbers time	150
italian	greetings verbs travel food numbers time	150
vietnamese	greetings numbers food travel phrases	90

Trivia

Theme	Subtypes	Entries
oscars	classics 1960s-70s 1980s-90s 2000s-10s 2020s	97
elements	periods-1-3 period-4 period-5 period-6 period-7	118
capitals	africa americas asia europe oceania	196
collectives	animals birds ocean people	61

You can use a category name to get everything in it (claude-spin-class languages), or narrow to a subtype (claude-spin-class http:4xx). claude-spin-class all loads all 1,281 entries.

How it works

Claude Code reads spinnerVerbs from ~/.claude/settings.json and cycles through the strings while it's processing. This tool just manages that field.

// ~/.claude/settings.json
{
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": [
      "400 → Bad Request: malformed syntax",
      "401 → Unauthorized: auth required",
      "403 → Forbidden: auth won't help"
    ]
  }
}

The tool always uses "mode": "replace" so your theme verbs are shown exclusively, rather than mixed in with Claude's defaults.

Contributing

Adding a theme is straightforward:

1. Create a JSON file in themes/<category>/ — keys are subtype names, values are string arrays
2. Add an entry to lib/catalog.js
3. Run npm test to make sure everything's wired up correctly
4. Open a PR

{
  "basics": ["Bonjour (Hello)", "Merci (Thank you)"],
  "numbers": ["Un (One)", "Deux (Two)"]
}

Ideas welcome — new languages, trivia categories, whatever seems fun to learn passively.

Development

npm test

No dependencies. Uses Node's built-in test runner. The suite validates catalog integrity (file exists, subtypes present, no empty arrays, all entries are strings) and core resolution logic. New themes get covered automatically.

CI/CD

Tests run automatically on every push to main and on all PRs, against Node 18, 20, and 22.

Releases are published to npm via npm Trusted Publishers (OIDC — no token stored in GitHub secrets). To publish a new version:

npm version patch   # or minor / major
git push --tags

The tag push triggers the publish workflow, which runs tests and then publishes with provenance.

License

MIT — see LICENSE.