Hammerspoon — macOS Lua 자동화 프레임워크
macOS 시스템 API를 Lua 스크립트로 제어하는 오픈소스 자동화 도구
개요
Hammerspoon은 macOS와 Lua 스크립팅 엔진 사이의 브릿지 역할을 하는 자동화 도구다. 단순한 키 리매핑부터 윈도우 관리, 시스템 이벤트 후킹, 네트워크 모니터링까지 Lua 코드 하나로 제어할 수 있다.
아키텍처
macOS API ←→ Objective-C Extensions ←→ Lua Engine ←→ init.lua (사용자 스크립트)
- 코어는 브릿지 — OS 기능을 Lua에 노출
- 확장(Extensions)이 각 시스템 영역 담당
- Spoons: 사전 제작된 재사용 플러그인
- 설정: ~/.hammerspoon/init.lua 하나로 모든 것을 관리
주요 API
| API | 기능 |
|---|---|
| hs.eventtap | 저수준 키보드/마우스 이벤트 후킹 |
| hs.keycodes | 입력 소스 감지 및 전환 |
| hs.hotkey | 글로벌 핫키 바인딩 |
| hs.window | 윈도우 배치/관리 |
| hs.application | 앱 제어 |
| hs.alert | 화면 알림 |
| hs.timer | 타이머/스케줄링 |
| hs.wifi | Wi-Fi 상태 모니터링 |
| hs.location | 위치 서비스 |
| hs.clipboard | 클립보드 관리 |
한영 전환 활용법
한국 사용자들이 캡스락 한영전환 딜레이를 해결하기 위해 적극 활용하는 패턴:
기본 한영 전환 (Shift+Space)
Lua 스크립트로 hs.keycodes.currentSourceID()로 현재 입력 소스를 감지하고, hs.keycodes.currentSourceID(nextInput)로 전환. hs.hotkey.bind()로 단축키 바인딩.
Vim ESC → 자동 영문 전환
hs.eventtap으로 ESC 키 이벤트를 후킹, 현재 입력 소스가 영문이 아니면 hs.eventtap.keyStroke({}, ‘right’)로 한글 마지막 글자를 보존한 뒤 영문으로 전환.
시각적 입력 소스 알림
hs.keycodes.inputSourceChanged() 콜백에서 hs.alert.show()로 현재 입력 소스를 화면에 표시.
설치
brew install —cask hammerspoon
설치 후 ~/.hammerspoon/init.lua에 스크립트 작성. 메뉴바 → Hammerspoon → Reload Config로 즉시 적용.
장단점
장점
- Lua 스크립트로 무한 확장 가능
- 커뮤니티 Spoons 생태계
- 디버깅용 내장 콘솔
- API 문서가 잘 정리됨
단점
- 스크립트 작성/유지보수 부담
- 입력 모니터링 권한 필요
- Lua 학습 곡선
- 타 도구 대비 설정이 번거로움
경쟁 도구 비교
| 관점 | Hammerspoon | Karabiner | FOCD |
|---|---|---|---|
| 성격 | 범용 자동화 | 키보드 전용 | 한영전환 전용 |
| 언어 | Lua | JSON 프로필 | Swift (네이티브) |
| 확장성 | 무한 | 키매핑 한정 | 없음 |
| 진입장벽 | 중간 | 낮음~중간 | 매우 낮음 |
| 한영전환 | 스크립트 필요 | F13 리매핑 | 원클릭 |
한영전환만 필요하면 2026-04-14-focd-capslock-delay-fix가 더 간편하지만, 윈도우 관리, 핫키, 시스템 자동화까지 필요하면 Hammerspoon이 압도적이다.
참고 자료
- 기계인간 John Grib - Hammerspoon 튜토리얼 (https://johngrib.github.io/wiki/hammerspoon-tutorial-03/)
- kumas.dev - macOS 한영 전환 단축키 변경 (https://kumas.dev/posts/mac-hammerspoon)
- WONJOON.LOG - Vim ESC 자동 영문 전환 (https://wnjoon.github.io/ko/hammerspoon-key-switch/)
관련 노트
- 2026-04-14-focd-capslock-delay-fix — 캡스락 한영전환 딜레이 전용 해결 도구 (Swift)