/voice — Forge Voice 셋업 & 관리

code-forge의 음성 입력 확장. 대장간 비유: Anvil(작업대)에 명령을 외치면 → Forge Voice가 받아 → Smith/Implementor가 단조.

서브커맨드

/voice setup — 1회 셋업

다음을 순서대로 실행 (사용자 확인 받으면서):

1. 의존성 점검

for cmd in sox whisper-cpp jq; do
  command -v "$cmd" >/dev/null 2>&1 || echo "  ❌ $cmd 없음"
done
command -v cliclick >/dev/null 2>&1 || echo "  ⚠️ cliclick 없음 (옵션, 자동 paste 정확도 ↑)"
brew list --cask hammerspoon >/dev/null 2>&1 || echo "  ❌ Hammerspoon 없음"

누락 시 사용자에게 한 줄 install 안내:

brew install whisper-cpp sox jq cliclick
brew install --cask hammerspoon

2. Whisper 모델 다운로드

~/.whisper/models/ggml-small.bin 없으면:

mkdir -p ~/.whisper/models
curl -fsSL -o ~/.whisper/models/ggml-small.bin \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin

→ 244MB, 한국어 OK. medium 모델은 사용자에게 옵션 제안 (1.5GB, 정확도 ↑↑).

3. forge-voice 스크립트 + Lua 설치

mkdir -p ~/.local/bin ~/.local/share/forge-voice ~/.hammerspoon

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(claude plugin path code-forge)}"

cp "$PLUGIN_ROOT/tools/forge-voice.sh" ~/.local/bin/forge-voice.sh
chmod +x ~/.local/bin/forge-voice.sh

cp "$PLUGIN_ROOT/tools/forge-voice.lua" ~/.local/share/forge-voice/forge-voice.lua

4. Hammerspoon init.lua 등록

~/.hammerspoon/init.lua에 1줄 (중복 안 들어가게 grep 체크):

LINE='dofile(os.getenv("HOME") .. "/.local/share/forge-voice/forge-voice.lua")'
if ! grep -qF "forge-voice.lua" ~/.hammerspoon/init.lua 2>/dev/null; then
  echo "$LINE" >> ~/.hammerspoon/init.lua
fi

→ Hammerspoon 메뉴바 → Reload Config 안내.

5. macOS 권한 안내

사용자에게 직접 허용해야 하는 항목:

• 시스템 환경설정 → 보안 → 마이크: Hammerspoon 허용
• 시스템 환경설정 → 보안 → 접근성: Hammerspoon 허용 (cliclick 사용 시)

→ 본 단계는 시스템 권한이라 자동화 불가. 사용자 직접 수행 후 /voice test.

6. 사용 안내

⌘ + Shift + Space 단축키 3가지:

• ⌘⇧Space — 토글 (한 번 녹음 시작, 다시 누르면 종료)
• ⌘⇧. — silence detection (말 멈추면 자동 종료)
• ⌘⇧, — 상태 확인

/voice test — 풀 회로 검증

1. forge-voice.sh status → idle 확인
2. 사용자에게 "지금 ⌘⇧Space 누르고 '테스트 일이삼' 말해보세요" 안내
3. 5초 후 ~/.local/share/forge-voice/last.txt 확인 → 결과 표시
4. (옵션) UserPromptSubmit hook 확인 — code-forge/hooks/auto-flow-trigger.sh 존재 + 실행 권한

/voice doctor — 트러블슈팅

진단 항목:

/voice uninstall

되돌리기:

rm -f ~/.local/bin/forge-voice.sh
rm -rf ~/.local/share/forge-voice
# Hammerspoon init.lua 에서 dofile 라인 제거
sed -i '' '/forge-voice.lua/d' ~/.hammerspoon/init.lua
# Hammerspoon Reload Config

→ Whisper 모델 (~244MB)은 사용자에게 유지/삭제 선택 받음.

발화 패턴 (음성 친화 prompt 가이드)

1. 자연어 의도 전달 (권장)

자연어로 의도만 전달, Claude가 코드 작성:

2. 자주 쓰는 단축 vocabulary

3. 코드 dictation은 한계

코드 직접 dictation (예: "open paren foo close paren")은 본 stack의 한계. RSI 영구화 우려 시 Talon Voice 학습 (1-2주, 무료) 권장.

본 Forge Voice는 자연어 의도 → Claude 코드 작성 패턴에 최적화. 손목 보호 + 표현 속도 우선.

통합 진입점

본 스킬은 code-forge family의 정식 일부:

• 코어 도구: tools/forge-voice.sh (스크립트)
• Hammerspoon hook: tools/forge-voice.lua
• 가이드: docs/voice-input.md (상세 reference)
• 자연어 → flow CLI hook: hooks/auto-flow-trigger.sh (G5 — 음성 입력에도 그대로 작동)
• 통합 계약: docs/contracts/INTEGRATION.md §11

→ 음성 입력은 별도 도구가 아니라 code-forge family의 확장.