Claude Code Spinner

Warning

작업 중 (Work in Progress) 현재 렌더링 이슈를 수정 중입니다. 일부 환경에서 스피너가 올바르게 표시되지 않을 수 있습니다.

Claude Code 작업 중 터미널에 레트로 ASCII 스피너를 렌더링합니다.

/dev/tty(Unix) / CONOUT$ 또는 CON(Windows)에 직접 ANSI escape sequence를 쓰는 방식이므로 Claude Code의 Ink 렌더링 파이프라인과 별도로 동작합니다. Ink 또는 터미널 스크롤이 같은 영역을 다시 그릴 수 있으므로 overlay 데몬은 높은 주기로 프레임을 다시 그리고, 종료 시에는 렌더링 영역을 정리합니다.

Windows, Linux, macOS 지원. Python 3.8+.

동작 원리

1. Hook — UserPromptSubmit 이벤트에서 overlay 데몬을 fork하여 백그라운드 실행
2. Overlay 데몬 — TTY를 직접 열고(기본 /dev/tty, tmux 환경에서는 pane TTY fallback), 터미널 크기를 감지하여 NxM 스피너를 지정 위치에 프레임 단위로 렌더링
3. Hook — Stop/StopFailure/SessionEnd 이벤트에서 overlay 데몬을 종료하고 영역을 정리

SIGWINCH 수신 시 터미널 크기를 재측정하고, auto 모드에서는 스피너를 동적으로 리사이징합니다. Windows에서는 보이는 셸 콘솔에 붙기 위해 부모 프로세스 체인과 알려진 콘솔 호스트를 순서대로 검사합니다.

스피너 카탈로그

python3 claude_code_spinner.py list

사용 가능한 스피너:

crt_bar

|=>   |

pipe

/

braille

.

variation_1

\\
  \\
    \\
      \\
        \\

variation_2

\\
  \\
    \\

variation_3

   o * .
 0       .
@         .
 .       .
   . . .

variation_4

  0 o
@     .
  . .

설치

# Unix
python3 install.py

# Windows PowerShell
python .\install.py

설치 후 Claude Code 재시작.

활성화 / 비활성화

설치 후 Claude Code 세션 내에서 slash command로 토글할 수 있습니다:

/spinner status    # 현재 상태 확인
/spinner enable    # 스피너 활성화 (hooks 등록)
/spinner disable   # 스피너 비활성화 (hooks 제거)
/spinner debug-on  # 훅/데몬 로그 활성화
/spinner debug-off # 훅/데몬 로그 비활성화
/spinner log       # 최근 로그 출력

CLI에서 직접 실행도 가능합니다:

python3 ~/.claude/claude-code-spinner/claude_code_spinner.py enable
python3 ~/.claude/claude-code-spinner/claude_code_spinner.py disable
python3 ~/.claude/claude-code-spinner/claude_code_spinner.py status
python3 ~/.claude/claude-code-spinner/claude_code_spinner.py debug-on
python3 ~/.claude/claude-code-spinner/claude_code_spinner.py log -n 100

설정

~/.claude/claude-code-spinner/config.json:

{
  "spinner": "auto",
  "theme": "sprite",
  "position": "top-right",
  "margin_row": 1,
  "margin_col": 2,
  "max_width_ratio": 0.25,
  "max_height_ratio": 0.33,
  "color": "1;36",
  "idle_clear": true,
  "redraw_hz": 100,
  "statusline": {
    "enabled": false,
    "spinner": "variation_3",
    "label": "CRT",
    "show_model": true,
    "show_git": true,
    "show_cost": true,
    "show_elapsed": true
  },
  "debug": false
}

spinner

스피너 이름(variation_1 ~ variation_4, crt_bar, pipe, braille)을 직접 지정하거나 "auto"로 크기에 맞는 스피너를 자동 선택.

position

"top-right", "top-left", "bottom-right", "bottom-left" 또는 {"row": N, "col": M} (1-indexed 절대좌표).

max_width_ratio / max_height_ratio

auto 모드에서 터미널 크기 대비 스피너가 차지할 수 있는 최대 비율. 터미널이 80x24라면 0.25는 가로 20자, 0.33은 세로 8행까지.

color

ANSI 색상 코드. "1;36" = bold cyan, "1;32" = bold green, "38;5;214" = orange 등.

idle_clear

true이면 overlay 데몬 종료 시 스피너 영역을 공백으로 정리합니다.

redraw_hz

Ink나 다른 렌더러가 overlay 영역을 지웠을 때 다시 그리는 주기입니다. 기본값 100은 최대 약 10ms 안에 다시 그리는 설정입니다.

statusline

"enabled": true로 설정하면 overlay와 별도로 statusLine 렌더러도 활성화합니다. statusLine은 1행짜리 인라인 스피너를 Claude Code 하단 상태줄에 표시합니다. 여러 줄 스피너를 statusLine에 지정하면 crt_bar로 대체됩니다.

tmux 환경

• CLAUDE_CODE_SPAWN_BACKEND=tmux 환경에서도 동작하도록 tmux pane TTY fallback을 사용합니다.
• pane 선택이 필요한 경우 아래 환경변수를 지정할 수 있습니다.
  • CLAUDE_SPINNER_TMUX_TARGET (예: %12, mysession:1.2)
  • CLAUDE_SPINNER_TTY (직접 TTY 경로 강제 지정, 예: /dev/pts/7)

hook 디버깅

• config.json에서 "debug": true 또는 환경변수 CLAUDE_SPINNER_DEBUG=1을 주면 훅/데몬 로그가 남습니다.
• 로그 파일: ~/.claude/claude-code-spinner/debug.log
• CLI에서 debug-on, debug-off, log, log -n N, log --clear 명령을 사용할 수 있습니다.