orthodox-spinner ☦

A terminal spinner shaped like an orthodox cross that breathes in and out.

☦  npm install

The ☦ pulses from bright to dim while any command runs, then clears — replacing whatever spinner the tool would have shown.

Installation

Recommended (isolated CLI tool):

pipx install git+https://github.com/samsonofzorah/orthodox-spinner.git

macOS + Homebrew Python 3.14 note: if pipx errors with ImportError: dlopen … pyexpat, pipx's shared env is on Python 3.14 which has a broken libexpat on macOS. Fix it with:

PIPX_DEFAULT_PYTHON=/opt/homebrew/bin/python3.12 pipx install git+https://github.com/samsonofzorah/orthodox-spinner.git

Or with pip (Python 3.11–3.13 all work):

pip install git+https://github.com/samsonofzorah/orthodox-spinner.git

CLI usage

Wrap any command — its output is buffered and shown after the spinner clears:

spin npm install
spin make build
spin -m "Deploying…" ./deploy.sh

Python library

from orthodox_spinner import Spinner

# context manager
with Spinner("installing"):
    subprocess.run(["npm", "install"])

# manual control
s = Spinner("building").start()
do_work()
s.stop()

Shell integrations

To replace the built-in spinners of common tools system-wide, source the provided shell file in your ~/.zshrc:

echo 'source /path/to/orthodox-spinner/shell/orthodox_spinner.zsh' >> ~/.zshrc

Or copy the relevant functions directly into your ~/.zshrc.

Covered tools: npm, pip, pip3, brew, yarn, cargo

Each wrapper only activates for slow subcommands (install, build, update, etc.) and falls through to the real binary for everything else.

How it works

spin <cmd> runs the command with its stdout/stderr captured, shows the breathing ☦ spinner on stderr, then flushes the buffered output once the command exits. The spinner is written to stderr so it does not pollute piped output.

The animation uses ANSI 256-color grayscale codes (no dependencies beyond the Python standard library).

Requirements

• Python ≥ 3.8
• A 256-color terminal (iTerm2, Terminal.app on macOS, most modern terminals)