Claude Code Spinner Verbs: Customize Them (Team Playbook)

Claude Code spinner verbs are the short words shown next to the loading spinner while Claude Code thinks — the defaults rotate through things like "Vibing", "Pondering", and "Schlepping". You customize them by adding a spinnerVerbs block to your settings.json with a mode (replace or append) and a list of verbs. Restart Claude Code and your words show up. That's the whole feature: cosmetic, safe, and easy to share with a team.

This is a small thing you see hundreds of times a day. When the words are intentional, the tool feels more like yours. When you share one list across a team, every terminal speaks in the same voice. Below is exactly how to set it up, how to choose between replace and append, how to build a themed pack that doesn't get old, and how to roll one config out to everyone.

What are Claude Code spinner verbs?

Spinner verbs are the rotating status words Claude Code shows while it works on your request. They sit right next to the animated spinner in the terminal. By default Claude ships a playful set, and they change every second or so while a task runs.

They are purely cosmetic. They do not change what Claude does, how it reasons, or how fast it responds — they only change the word you read while you wait. That makes them low-risk to edit: a typo in your verb list can't break a build or corrupt a session. The worst case is a word you don't like, which you fix in one line.

People customize them for two reasons. First, identity — a team that builds websites with Claude Code can make the spinner say "Mapping the scope" instead of a generic default, so the tool reads like part of their own workflow. Second, fun — themed packs (One Piece, Star Wars, your team's inside language) make a repetitive surface feel alive. Both are valid. The trick, covered further down, is keeping personality without turning the spinner into noise you have to read past.

How do I customize Claude Code spinner verbs in settings.json?

Add a spinnerVerbs block to your Claude Code settings.json, then restart. Here is the minimal version:

{
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": [
      "Mapping the scope",
      "Pressure-testing assumptions",
      "Composing the patch",
      "Tracing edge cases"
    ]
  }
}

Two fields do the work:

• mode — replace shows only your verbs; append mixes your verbs in with the defaults.
• verbs — an array of strings. Each string is one spinner phrase.

Where you put the file decides who sees it:

• ~/.claude/settings.json — your personal, machine-wide config. Affects every project you open.
• .claude/settings.json in a repo — project-level config that travels with the codebase. Good for a team, because the words live next to the code and get reviewed in pull requests.

After you save, restart Claude Code so it reloads settings. If your verbs don't appear, check that the JSON is valid (a trailing comma is the usual culprit) and that you're editing the file scope you think you are — a project .claude/settings.json overrides your global one. Because this file is the same one that controls permissions and hooks, keep your edits inside the spinnerVerbs block and leave the rest alone.

Replace vs append: which mode should I use?

Use append while you're experimenting and replace once you want a consistent voice. append keeps the familiar defaults in rotation alongside your new words, so nothing feels like it disappeared. replace gives you full control — every word on screen is one you chose.

Here is how the two compare in practice:

The rule of thumb: append is the safe default for trying things, replace is the right call once you've decided the spinner should say your words and only your words. A themed pack almost always wants replace, because a single stray default verb breaks the illusion.

How do I build a themed spinner verb pack that doesn't get old?

The mistake most people make is writing 40 jokes. A pure meme list is fun for two days and distracting by day five — you start reading every word instead of letting it blur. The fix is a small design system with constraints, so the pack stays fresh and stays out of your way.

Four rules carry most of the weight:

1. Keep each phrase to 2–5 words. Long spinner text wraps badly and adds visual friction. Short verbs read at a glance.
2. Prefer action language over jokes. "Tracing dependencies" ages better than a one-off reference. Aim for roughly 80% practical verbs, 20% flavor.
3. Group verbs by intent so the rotation has variety without chaos. A clean split: analysis (mapping, exploring, reading), execution (building, patching, shipping), validation (testing, checking, verifying), and polish (refining, tightening, documenting).
4. Avoid words that imply false completion. Skip "Done" or "Fixed" mid-task — keep everything process-oriented, because the spinner is showing work in progress.

Here is a neutral 30-item starter you can drop straight into the verbs array. It has personality but reads as serious work:

[
  "Mapping the problem",
  "Parsing the context",
  "Reading constraints",
  "Comparing tradeoffs",
  "Tracing dependencies",
  "Locating bottlenecks",
  "Drafting approach",
  "Composing the patch",
  "Staging the rollout",
  "Shaping the flow",
  "Polishing microcopy",
  "Refining hierarchy",
  "Testing assumptions",
  "Running QA checks",
  "Validating edge cases",
  "Checking fallback paths",
  "Hardening behavior",
  "Smoothing interactions",
  "Tightening latency",
  "Guarding accessibility",
  "Reviewing metrics",
  "Calibrating signal",
  "Aligning the brief",
  "Stress-testing logic",
  "Preparing handoff",
  "Cleaning artifacts",
  "Updating docs",
  "Packaging insights",
  "Locking confidence",
  "Shipping with care"
]

For a fun pack, keep the same constraints and swap the vocabulary — a One Piece set might use "Setting the log pose" or "Gear second engaged", but still 2–5 words and still grouped by intent. The structure is what keeps it from getting old, not the topic.

How do I share spinner verbs across a team?

Put the spinnerVerbs block in a project-level .claude/settings.json that's committed to the repo. Now the config travels with the code: anyone who clones the project gets the same spinner words, and any change to the list shows up in a pull request like normal code. This is the same idea behind a shared CLAUDE.md — knowledge that lives in the repo instead of scattered across personal machines, which we cover in CLAUDE.md progressive disclosure for fast teams.

A clean rollout takes about a week, low-risk the whole way:

• Day 1 — set the tone. Decide serious, playful, or mixed. Name banned patterns (inside jokes that don't scale, ambiguous slang). Pick one owner for list quality.
• Day 2 — draft the bank. Write 40–60 candidates, cut anything too long, land on a final 20–35.
• Day 3 — readability test. Try it in your real terminal width, in both dark and light themes. Remove anything that clutters the spinner area.
• Day 4 — choose mode and scope. append for the trial, replace once it's stable. Commit it to the project .claude/settings.json.
• Day 5 — document and ship. Add a short README note: what it is, who owns it, how to propose changes, and how to opt out for personal preference.

Two cautions from running shared config in real teams. Keep one maintainer and review edits in the normal pull-request flow — without an owner, lists drift across machines. And lead with intent, not a surprise: people resist a forced cosmetic change they don't understand, but accept "this is our voice, here's why" with an opt-out. We treat tooling language like any team-wide default in our supervised research-to-ship loop — small change, fast feedback, easy to undo.

FAQ

Do Claude Code spinner verbs change how Claude works?

No. Spinner verbs are purely cosmetic — they only change the word displayed next to the loading spinner while Claude thinks. They have no effect on Claude's reasoning, output, speed, or behavior. You can edit them freely without any risk to your sessions or builds.

Where is the settings.json file for spinner verbs?

There are two scopes. Your personal config lives at ~/.claude/settings.json and applies to every project. A project-level config lives at .claude/settings.json inside a repo and applies only to that project. The project file overrides the global one, which is why teams commit spinner verbs at the project level so everyone shares the same list.

What's the difference between replace and append mode?

replace shows only the verbs you list — full control, nothing else appears. append adds your verbs to Claude Code's built-in defaults, so both show up in rotation. Use append while experimenting and replace once you want a consistent, branded voice or a themed pack where every word must fit.

Why aren't my custom spinner verbs showing up?

Three common causes. First, you didn't restart Claude Code after editing — settings load on start. Second, invalid JSON, usually a trailing comma in the verbs array. Third, a project-level .claude/settings.json is overriding your global file, so check which scope you actually edited.

How many spinner verbs should I keep?

Around 20–35 is the sweet spot. Fewer than that starts to feel repetitive on a long task, and many more dilutes quality and lets weak phrases slip in. Cap the list, keep one owner, and refresh it every quarter or so as stale phrases pile up.

Can spinner verbs become distracting?

Yes, if you let them. Long phrases that wrap, joke-heavy lists you have to actually read, and words that imply false completion ("Done" mid-task) all pull focus. Keep verbs to 2–5 words, lean about 80% action language to 20% flavor, and test them in your real terminal width before shipping.