claude-code-spinner: replacing Claude Code's spinner phrases with 90+ Russian one-liners

What claude-code-spinner changes, and for whom

Claude Code shows a rotating word while the model works. The README lists the defaults as Thinking..., Analyzing... and Pondering.... claude-code-spinner replaces that rotation with Russian phrases such as "Обкашляю вопросик" and "По красоте все сделаем", and the README claims more than 90 phrases in total. The stated audience is "уважаемые вайбкодеры", a joking label for people who drive an agent from the terminal rather than writing every line by hand.

The scope is deliberately narrow. Nothing here changes model behaviour, tool permissions or output formatting. It changes what the terminal prints while you wait, and optionally plays a sound when a turn ends. If you never look at the spinner, this project has nothing to offer you.

How the spinner replacement works: settings.json and spinnerVerbs

There is no daemon and no wrapper binary. The whole mechanism is Claude Code's own settings file. The README shows the shape of the entry, with a mode key and a verbs array:

{
  "spinnerVerbs": {
    "mode": "replace",
    "verbs": ["Обкашляю вопросик", "По красоте все сделаем", "..."]
  }
}

The repository keeps the full phrase list in spinners.json at the top level, alongside hooks.json, a sounds/ directory and a .claude/ directory that holds the slash commands. Installation is therefore a copy operation: the phrases in spinners.json end up inside the spinnerVerbs block of ~/.claude/settings.json.

The mode value matters. It is set to replace, which means the custom list substitutes for the built-in words rather than adding to them. If you were expecting the default English words to remain in rotation alongside the Russian ones, this configuration does not do that. The README does not describe an append mode, so anyone who wants both lists would have to merge the arrays by hand before writing the file.

Installing claude-code-spinner and running it once

The README gives two paths. The first assumes you have Claude Code open and can run its slash commands. Clone the repository first:

git clone https://github.com/i1kazantsev/claude-code-spinner.git
cd claude-code-spinner

Then, inside Claude Code, run the command the README documents:

/install-spinner

According to the README, that command copies the contents of spinners.json into ~/.claude/settings.json for you. You should see the spinner change on the next turn, and the new phrases appear where Thinking... used to be.

The manual route is to open spinners.json, copy its contents, and paste them into the spinnerVerbs key of ~/.claude/settings.json yourself. The README shows the target structure with mode set to replace and a verbs array. This is the path to take if you already have a settings file with other keys in it and want to see exactly what is being added before it lands.

The Stop hook sound and the afplay dependency

The second feature is a sound played when the main agent finishes a response. The README calls it "Вопросик на тормозах" and wires it to the Stop hook. The command is afplay, which the README notes is already present on macOS.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay -v 1 ~/.claude/sounds/stop-hook.mp3"
          }
        ]
      }
    ]
  }
}

Manual setup means copying sounds/stop-hook.mp3 into ~/.claude/sounds/ and adding that hook block to ~/.claude/settings.json. The /install-hook slash command does the same thing automatically. Volume is controlled by the -v flag; the README suggests changing -v 1 to -v 0.5 if the sound is too loud, and notes you can simply ask Claude to make it quieter.

The dependency is the real constraint here. afplay is a macOS utility. On Linux or Windows the hook will fail or silently do nothing, and the README does not offer an alternative player or a cross-platform command. The spinner phrase replacement itself is plain JSON and is not tied to any operating system, so the two features have different portability.

Limitations, failure modes and when to skip it

The most obvious failure mode is a bad merge. If you paste the spinnerVerbs block into a settings file that already contains other keys, a single misplaced brace breaks the whole file, and Claude Code may fall back to defaults or refuse the configuration. The README does not document a validation step or a rollback procedure, and there is no mention of what happens to a malformed settings.json.

Second, mode: replace is destructive to the previous verb list. There is no documented way to restore the original Thinking..., Analyzing... and Pondering... words other than deleting the spinnerVerbs key or reinstalling. The README does not describe an uninstall command for either /install-spinner or /install-hook.

Third, the project has no releases. The repository was last pushed on 2026-05-06, and there is no version number, changelog or tag to pin. If the phrase list changes upstream, you get the change on your next git pull with no diff summary.

Finally, the README opens with a warning that malicious copies of the project exist and that the GitHub repository is the only official source. That is a supply-chain caution worth taking literally: the install path writes into a settings file that also governs hooks, and a hook is an arbitrary command.

How it compares with hand-editing spinnerVerbs

The honest alternative is not another tool. It is writing the spinnerVerbs block yourself in ~/.claude/settings.json and picking your own words. That approach has no dependency, no clone, and no third-party phrase list to trust. The difference in approach is curation versus authorship: claude-code-spinner hands you a fixed set of 90+ Russian phrases maintained by one person, while a hand-written block contains exactly the words you chose and nothing else.

A middle path is to clone the repository, read spinners.json, and copy only the phrases you like into your own settings file. You keep the convenience of a ready-made list without running the slash commands, and you avoid pulling in the hooks.json configuration if you do not want a Stop sound. The README supports this reading: the manual installation section is presented as a first-class option, not a fallback.

Maintenance cost, licence and what to verify

The README answers the licence question in one line: "Какая еще лицензия? Ладно, MIT." So the project is MIT-licensed, which in practice means you can copy, modify and redistribute it, including the phrase list, provided the licence terms are honoured. The repository does not include a LICENSE file at the top level according to its directory listing, so the licence statement lives only in the README. If you need a licence file for compliance tooling, that is a gap to check before vendoring the phrases.

Upgrade cost is low but unversioned. There are no releases, so the only upgrade path is git pull. The files that matter are spinners.json and hooks.json; diffing those two after a pull tells you everything that changed. Because the settings file is outside the repository, an upstream change does not propagate automatically: you re-run /install-spinner or paste the new list again.

The last push was on 2026-05-06, which is more than four months before today's date. The repository is not archived, but there is no release history and no stated support commitment. Treat it as a personal configuration kit that happens to be public.

Editorial conclusion

Adopt claude-code-spinner if you already run Claude Code, want the spinner to read in Russian, and are comfortable editing or replacing ~/.claude/settings.json. Skip it if you need a maintained, versioned package with a changelog, or if you work on a machine without afplay. Before installing, open spinners.json and hooks.json and read the exact JSON they write, then back up your existing settings file, because mode: replace overwrites the verb list rather than appending to it. The repository was last pushed on 2026-05-06 and carries no releases, so treat it as a personal configuration kit rather than a dependency.

Frequently asked questions

Official sources

1. i1kazantsev/claude-code-spinner on GitHub
2. Issues
3. README