문제: Claude Code는 기다려주지 않는다
Claude Code를 쓰다 보면 이런 상황이 반복된다:
- Claude에게 작업을 시키고 브라우저로 전환
- 한참 뒤에 돌아와보니 “권한 승인 대기 중“에서 멈춰있다
- 또는 이미 끝났는데 모르고 한참을 기다린다
터미널을 계속 쳐다보고 있을 수도 없고, 다른 일을 하자니 Claude가 언제 날 부르는지 알 수가 없다.
그런데 손에 쥐고 있는 마우스가 진동으로 알려준다면?
claude-code-logitech-haptic-plugin
claude-code-logitech-haptic-plugin은 Claude Code의 이벤트를 Logitech MX Master 4의 햅틱 모터와 연결해주는 플러그인이다.
작동 원리는 단순하다:
Claude Code 이벤트 → Hook → 쉘 스크립트 → HTTP API → HapticWebPlugin → MX Master 4 진동
Claude Code는 hooks 시스템을 통해 특정 이벤트 발생 시 외부 스크립트를 실행할 수 있다. 이 플러그인은 그 hook에 햅틱 API 호출을 연결한 것이다.
어떤 상황에서 진동하는가
세 가지 이벤트에 각각 다른 진동 패턴이 매핑되어 있다:
| 상황 | 진동 패턴 | 느낌 |
|---|---|---|
| 권한 승인 요청 | knock | 톡톡 — 노크하듯 두 번 |
| 60초 이상 입력 대기 | ringing | 르르르 — 전화 오듯 울림 |
| 작업 완료 | completed | 뚝 — 깔끔한 완료 펄스 |
손바닥에 닿아 있는 마우스에서 미세한 진동이 오기 때문에, 다른 모니터를 보거나 문서를 읽고 있어도 바로 알 수 있다. 소리 알림과 달리 주변 사람을 방해하지도 않는다.
MX Master 4 사용자에게 추천하는 이유
MX Master 4는 Logitech 마우스 중 햅틱 스크롤 휠이 탑재된 몇 안 되는 모델이다. 이 햅틱 모터를 스크롤 피드백 외에도 활용할 수 있게 해주는 것이 HapticWebPlugin이고, 이 플러그인은 그것을 Claude Code와 연결한다.
이미 MX Master 4를 쓰고 있다면 추가 하드웨어 없이 소프트웨어만으로 완성된다.
설치
1단계: HapticWebPlugin 설치
Logi Options+에서 플러그인을 설치한다:
- Logi Options+ 열기 → MX Master 4 선택
- HAPTIC FEEDBACK 탭 → 설정(⚙️) 클릭
- INSTALL AND UNINSTALL PLUGINS 버튼
- 레포의
plugin/HapticWeb.lplug4파일을 더블클릭 - Continue로 설치 완료
설치 확인: haptics.jmw.nz/playground에서 진동 패턴을 테스트해볼 수 있다.
2단계: Claude Code 플러그인 설치
git clone https://github.com/ChefJodlak/claude-code-logitech-haptic-plugin.git
cd claude-code-logitech-haptic-plugin
./install.sh
설치 스크립트가 자동으로:
- OS 감지
- HapticWebPlugin 연결 확인
~/.claude/hooks/디렉토리에 스크립트 설치~/.claude/settings.json에 hook 설정 추가- 테스트 진동 실행
3단계: Claude Code 재시작
Hook 설정은 시작 시 로드되므로, 실행 중인 Claude Code를 재시작하면 바로 적용된다.
진동 패턴 커스터마이징
기본 매핑이 마음에 들지 않으면 ~/.claude/hooks/haptic-trigger.sh에서 변경할 수 있다:
WAVEFORM_PERMISSION="knock" # 권한 요청
WAVEFORM_IDLE="ringing" # 입력 대기
WAVEFORM_COMPLETE="completed" # 작업 완료
선택 가능한 진동 패턴이 15가지나 된다:
| 분류 | 패턴 |
|---|---|
| 정밀 피드백 | sharp_collision, damp_collision, subtle_collision, damp_state_change |
| 진행/완료 | sharp_state_change, completed, firework, happy_alert, wave |
| 긴급 알림 | angry_alert, mad, square |
| 수신 알림 | knock, ringing, jingle |
작업 완료 시 firework(축하 폭죽 패턴)을 쓰면 기분이 좋아질 수도 있다.
진동 강도 조절
Logi Options+ → MX Master 4 → Haptic Feedback → Strength 슬라이더로 조절한다. Subtle, Low, Medium, High 4단계가 있다. API로는 강도 제어가 안 되고 Logi Options+에서만 가능하다.
동작 확인 및 트러블슈팅
# HapticWebPlugin 동작 확인
curl -s https://local.jmw.nz:41443/
# 수동으로 진동 테스트
curl -X POST -d "" https://local.jmw.nz:41443/haptic/completed
# hook 스크립트 수동 테스트
echo '{"hook_event_name": "Stop"}' | ~/.claude/hooks/haptic-trigger.sh
진동이 안 된다면:
- Logi Options+가 실행 중인지 확인
- MX Master 4가 연결되어 있는지 확인
~/.claude/hooks/haptic-trigger.sh에 실행 권한이 있는지 확인 (chmod +x)
제거
cd claude-code-logitech-haptic-plugin
./uninstall.sh
마치며
이 플러그인의 가치는 기술적 복잡성이 아니라 컨텍스트 스위칭 비용을 줄여준다는 점에 있다. Claude Code에게 작업을 시키고 다른 일을 할 수 있게 되면, AI 코딩의 실질적인 생산성이 달라진다.
MX Master 4 사용자라면 한 번 설치해볼 만하다. 설치에 5분도 안 걸리고, 되돌리기도 쉽다.