voice

name	voice
description	code-forge Forge Voice — 음성 입력 셋업 및 관리. 손목 부상/RSI 사용자가 family 워크플로우를 그대로 음성으로 쓸 수 있게. whisper.cpp + sox + Hammerspoon DIY stack. /voice setup으로 1회 셋업, /voice test로 동작 검증.
user-invocable	true

/voice — Forge Voice 셋업 & 관리

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

---

서브커맨드

사용	동작
/voice 또는 /voice setup	1회 셋업 (의존성 + 모델 + Hammerspoon 설정)
/voice test	동작 검증 (마이크 → STT → paste 풀 회로)
/voice status	현재 상태 (의존성 / 모델 / hook 활성)
/voice doctor	트러블슈팅 진단
/voice uninstall	셋업 되돌리기

---

/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 — 트러블슈팅

진단 항목:

증상	진단	해결
⌘⇧Space 안 먹힘	Hammerspoon menubar 활성	Reload Config / 재시작
"마이크 안 잡힘"	macOS 권한	시스템 환경설정 → 보안 → 마이크
녹음은 되는데 paste 안 됨	접근성 권한	환경설정 → 접근성 → Hammerspoon
한국어 인식률 낮음	small 모델	medium 또는 large 다운로드
영문 발음 모두 받는데 티켓 ID 안 잡힘	hook 누락	ls -la code-forge/hooks/auto-flow-trigger.sh 실행 권한
녹음이 안 끝남	silence 임계값	~/.local/bin/forge-voice.sh 의 silence 인자 조정

---

/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가 코드 작성:

발화	결과
"프로젝트 일이삼 작업 시작" → Whisper → "PROJ-123 작업 시작"	G5 hook → flow tc select PROJ-123 자동
"통합 테스트 돌려"	Claude가 /test 또는 flow run report 호출
"이 버그 고쳐줘 — TypeError"	thinking-model GROUND "2-3 옵션 제시" 발화
"회고 보여줘"	flow retro

2. 자주 쓰는 단축 vocabulary

발화 (한국어)	Claude 해석
"스타트 [티켓]"	/start [티켓]
"테스트" or "테스트 돌려"	/test
"정리" or "정리해"	/cleanup
"디베이트 [주제]"	/debate [주제]
"리서치 [주제]"	/research [주제]
"도네" or "다 했어"	/done (commit + PR)

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의 확장.