Zundamon이 소리 내어 읽어주게 하세요

Claude Code는 훌륭합니다. 하지만 긴 응답이 돌아오면, 내내 화면을 쳐다보고 있어야만 합니다.

"화면을 계속 보고 있지 않아도 되도록, 그냥 이걸 나에게 읽어준다면 어떨까?"

그래서 저는 이것을 만들었습니다: voicevoice, Claude Code의 응답을 실시간으로 소리 내어 읽어주는 CLI입니다.

기본 목소리는 인기 있는 일본 합성 음성 캐릭터인 Zundamon입니다. 그 목소리가 Claude의 응답을 당신에게 읽어줍니다.

데모 영상 (GitHub)

3줄 설치법

brew install john-rocky/tap/voicevoice
voicevoice setup    # 여기서 VOICEVOX도 자동으로 설치합니다
voicevoice on

끝입니다. 평소처럼 claude를 실행하기만 하면, Zundamon이 응답이 돌아올 때마다 하나씩 읽어줍니다.

주요 기능

• Claude Code의 응답을 자동으로 읽어줌 (Auto-reads)
• 50개 이상의 캐릭터 목소리 간 전환 가능 (Zundamon, Shikoku Metan, Aoyama Ryusei 등)
• 완전 로컬 방식. 클라우드 API를 사용하지 않으며, 완전히 무료임
• OFF 상태일 때, Claude Code에 영향이 전혀 없음 (파일 하나를 확인하고 즉시 종료, 약 0.1ms)
• uninstall 한 번으로 환경을 완전히 복구 가능

사용법

기본 사용법

# 읽기 기능을 켜고 Claude 실행
voicevoice on
claude

대화 도중에 토글하려면:

! voicevoice off    # 음소거 (Claude 대화 중에 실행 가능)
! voicevoice on     # 재개

단독 실행도 가능

Claude Code 없이 일반적인 텍스트 음성 변환 (Text-to-speech) 도구로 사용할 수 있습니다.

voicevoice "Hello, nice weather today"

# 파이프 (pipes) 사용도 가능
...

목소리 변경

# 사용 가능한 캐릭터 목록 확인
voicevoice -l

Shikoku Metan: Normal(id=2), Sweet(id=0), Tsundere(id=6), Sexy(id=4), Whisper(id=36), Murmur(id=37)
Zundamon: Normal(id=3), Sweet(id=1), Tsundere(id=7), Sexy(id=5), Whisper(id=22), Murmur(id=38), Exhausted(id=75), Tearful(id=76)
Kasukabe Tsumugi: Normal(id=8)
...

50개 이상의 캐릭터와 다양한 스타일 중에서 선택할 수 있습니다. 즐겨 찾는 캐릭터를 저장하면 훅(hook) 기반의 자동 읽기 기능에서도 사용됩니다.

voicevoice config speaker 13    # Aoyama Ryusei(저장됨)로 전환
voicevoice config speed 1.3     # 약간 더 빠르게

작동 원리

Claude Code (응답 완료)
    ↓ Stop hook
voicevoice-hook.sh
...

이 도구는 Claude Code의 Stop hook을 사용합니다. 응답이 완료될 때마다 훅 스크립트가 실행되어 마지막 메시지를 가져온 뒤 VOICEVOX로 전달합니다.

주요 특징:

• 읽기 작업이 **백그라운드(background)**에서 실행됩니다. 음성이 재생되는 동안에도 다음 입력을 타이핑할 수 있습니다.
• 긴 응답은 500자에서 잘리며 "…(truncated)"가 붙습니다.
• 여러 세션에서 발생하는 오디오는 파일 잠금(file lock)을 통해 큐(queue)에 쌓입니다. 목소리가 서로 겹치지 않습니다.
• 모든 작업은 사용자의 Mac에서 실행됩니다. 인터넷이 필요하지 않습니다.

voicevoice setup이 수행하는 작업

설정(setup) 명령은 다음 과정을 자동으로 수행합니다:

1. VOICEVOX가 없는 경우 설치 (DMG 다운로드 → /Applications로 복사)
2. 훅 스크립트 생성 (~/.claude/hooks/voicevoice-hook.sh)
3. Claude Code의 settings.json에 훅 등록

기존 설정은 손상시키지 않습니다. 명령을 두 번 실행해도 중복 등록되지 않습니다.

삭제 (Uninstall)

voicevoice uninstall

이 명령만으로 다음 작업이 수행됩니다:

• settings.json에서 훅 등록 제거 (다른 설정은 그대로 유지)
• 훅 스크립트 삭제
• 모든 설정 및 플래그 파일 삭제

설정 전과 완전히 동일한 환경으로 돌아갑니다. 한 번의 실행으로 깔끔하게 제거되므로 부담 없이 시도해 보세요.

요구 사항

• macOS 14 이상 (Apple Silicon)
• Claude Code
• VOICEVOX — voicevoice setup을 통해 자동 설치됨
• jq — brew install jq

명령어 목록 (Command list)

마치며 (Closing)

코딩하는 내내 화면을 계속 지켜볼 필요는 없습니다. Zundamon이 핵심 내용을 알려주니까요.

스트레칭을 하거나, 커피를 내리거나, Claude의 응답을 듣는 것. 그런 종류의 개발 경험 (dev experience)은 솔직히 꽤 괜찮습니다.

저장소 (Repo):

https://github.com/john-rocky/voicevoice

brew install john-rocky/tap/voicevoice

VOICEVOX 캐릭터 음성을 공개적으로 사용하는 경우, 출처 표기가 필요합니다 (예: VOICEVOX:Zundamon). VOICEVOX 이용 약관을 확인하세요.

원문은 Qiita에 일본어로 게시되었습니다. GitHub / X