Hammerspoon은 macOS에서 단축키, 앱 실행, 키 입력 제어, 창 관리 같은 작업을 Lua 스크립트로 자동화할 수 있는 도구입니다. Windows의 AutoHotkey처럼 키보드 조합을 직접 지정하고 원하는 동작을 연결할 수 있어 macOS 자동화 환경을 본인에게 맞게 구성하는 데 도움이 됩니다.
macOS에서는 기본 단축키 설정만으로 해결하기 어려운 부분이 생각보다 많습니다. 예를 들어 특정 키 조합으로 앱을 실행하거나, 자주 사용하는 문구를 입력하거나, 상황에 따라 창을 이동하는 작업은 기본 설정만으로는 한계가 있습니다. Karabiner-Elements처럼 키보드 입력을 다루는 도구도 많이 사용되지만, 단순 키 매핑을 넘어 macOS 기능과 앱 동작까지 연결하려면 Hammerspoon이 더 적합할 수 있습니다.
필자의 경우 Windows에서는 AutoHotkey를 활용해 업무 효율을 높여왔지만, macOS로 넘어오면서 이를 대체할 만한 도구를 찾는 데 꽤나 어려움을 겪기도 했는데요. Hammerspoon은 처음에는 Lua 스크립트를 작성해야 해서 약간 낯설 수 있지만, 기본 구조만 이해하면 단축키 자동화, 한영 전환 보조, 앱 실행, 창 배치 같은 작업을 비교적 일관된 방식으로 관리할 수 있습니다. 다음 내용에서는 Hammerspoon 설치와 기본 사용법, 단축키 등록 방식, 키 이름과 키코드 확인 방법을 정리합니다. 보다 자세한 설명은 Hammerspoon 사용법 macOS 시스템 자동화 및 Lua 스크립트 설정 정리 문서에서 확인할 수 있습니다.
튜토리얼 환경: Mac OS-X Big sur. hammerspoon0.9.90 relese.
hammerspoon 이란
Hammerspoon은 macOS 자동화를 위해 사용하는 오픈소스 도구입니다. Hammerspoon 공식 문서에서는 이 도구를 macOS와 Lua 스크립팅 엔진을 연결하는 방식으로 설명하고 있으며, 사용자는 Lua 스크립트를 작성해 운영체제의 여러 기능을 제어할 수 있습니다.
쉽게 말하면 Hammerspoon은 macOS에서 사용할 수 있는 스크립트 기반 자동화 도구입니다. 단축키를 새로 만들거나, 특정 키 조합을 눌렀을 때 앱을 실행하거나, 창 위치를 옮기거나, 알림을 표시하는 등의 작업을 코드로 지정할 수 있습니다. 기본 macOS 설정에서는 제공하지 않는 동작을 사용자가 직접 구성할 수 있다는 점이 특징입니다.
Windows 환경에서 AutoHotkey를 사용해 본 경험이 있다면 Hammerspoon의 역할을 이해하기 쉽습니다. AutoHotkey처럼 키 입력과 동작을 연결할 수 있지만, Hammerspoon은 macOS의 여러 기능을 Lua 스크립트로 다루는 방식에 가깝습니다. 따라서 단순한 키 변경뿐 아니라 앱, 창, 클립보드, 알림, 오디오 장치, 네트워크 상태 등 다양한 macOS 기능을 함께 제어할 수 있습니다.
개인적으로는 다음과 같은 용도로 활용하기 좋습니다.
- 자주 사용하는 앱을 단축키로 실행
- 특정 키 조합으로 창 위치 이동
- macOS 기본 단축키와 다른 방식으로 키 조합 구성
- 한글과 영문 입력 전환 실수를 줄이기 위한 보조 설정
- 반복되는 작업을 Lua 스크립트로 자동화
- 클립보드, 알림, 메뉴바, 오디오 장치 등의 상태 제어
예를 들어 macOS에서 한영 전환이 자주 꼬이는 경우가 있습니다. 한글로 입력해야 하는데 영문으로 입력하거나, 반대로 영문을 입력해야 하는데 한글 상태로 입력해 다시 지우고 작성하는 상황입니다. 이런 경우 Hammerspoon을 이용하면 특정 단축키를 눌렀을 때 원하는 입력 소스로 전환하도록 구성할 수 있습니다.
필자의 경우 Windows와 macOS에서 최대한 비슷한 키보드 사용 방식을 유지하려고 합니다. 예를 들어 키보드 위치를 기준으로 특정 조합을 한글 입력, 다른 조합을 영문 입력으로 정해 두면 운영체제가 바뀌어도 입력 전환 실수를 줄일 수 있습니다. 다만 한영 전환 자동화는 macOS 입력 소스 이름과 사용 환경에 따라 코드가 달라질 수 있으므로, 이 글에서는 Hammerspoon의 기본 사용법을 먼저 정리합니다.
참고: macOS와 Windows를 함께 사용하는 경우에는 키 이름보다 실제 키보드 위치를 기준으로 단축키를 구성하는 편이 사용하기 편할 수 있습니다. 운영체제별 키 이름이 다르더라도 손의 위치가 같으면 적응이 더 쉽습니다.
hammerspoon 시작
Hammerspoon을 처음 사용하는 경우에는 먼저 앱을 설치하고, macOS 접근성 권한을 허용한 뒤, 설정 파일인 init.lua를 수정하는 순서로 진행하면 됩니다. Hammerspoon은 설치만으로 자동화가 바로 동작하는 방식이 아니라, 사용자가 설정 파일에 직접 Lua 코드를 작성해야 원하는 동작을 수행합니다.
공식 저장소 기준으로 Hammerspoon은 수동 설치와 Homebrew 설치를 모두 지원합니다. 수동 설치는 공식 릴리스 파일을 내려받은 뒤 Hammerspoon.app을 응용 프로그램 폴더로 옮기는 방식이고, Homebrew를 사용하는 경우에는 터미널에서 cask 설치 명령으로 설치할 수 있습니다.
설치
몇가지 설치 방법이 있지만 초보자 기준으로 가장 간편하게 다운로드 하고 설치 하는 방법을 안내합니다.
hammerspoon (1)을 검색 하고 아래 결과 페이지에서 hammerspoon.org (2)에 접속합니다.
hammerspoon 다운로드 메뉴가 보이는데 여기서 메뉴를 클릭합니다.
GitHub 릴리스 페이지로 이동하게 되는데 여기서 하단 최신 릴리스의 zip 파일을 다운로드합니다. 다운로드한 압축 파일을 해제한 뒤 Hammerspoon.app을 응용 프로그램 폴더로 이동합니다. 공식 저장소에서도 수동 설치 시 Hammerspoon.app을 Downloads 폴더에서 Applications 폴더로 옮기도록 안내하고 있습니다.
Homebrew를 사용하는 경우에는 터미널에서 다음 명령으로 설치할 수 있습니다. 홈브류 Homebrew 더 알아보기
brew install --cask hammerspoon
Hammerspoon (1) 파일을 마우스로 클릭해 실행한 뒤, 'Hammerspoon'은(는) 인터넷에서 다운로드된 앱입니다. 열겠습니까? 안내창이 표시되면 (2)를 눌러줍니다.
응용 프로그램 폴더에서 Hammerspoon을 실행합니다. 인터넷에서 다운로드한 앱이라는
Hammerspoon이 실행되면 메뉴 막대에 Hammerspoon 아이콘 (1) 이 표시됩니다. 처음 실행 시 Hammerspoon 설정 화면 (2) 이 열릴 수 있습니다. Hammerspoon 알림 (3)이 보여지고, macOS 자동화 기능을 사용하려면 접근성 권한을 허용해야 할 수 있습니다.
macOS Ventura 이후 버전에서는 보통 시스템 설정 > 개인정보 보호 및 보안 > 손쉬운 사용 경로에서 Hammerspoon을 허용할 수 있습니다. macOS 버전에 따라 메뉴 이름이나 위치가 조금 다를 수 있으므로, 설정 화면에서 손쉬운 사용 또는 접근성 항목을 기준으로 찾으면 됩니다.
- Dock에 아이콘을 생성하고 싶다면 Hammerspoon 설정 에서 체크합니다.
- 자동 시작을 하고 싶다면 Hammerspoon 설정 에서 에 체크합니다.
- 클릭 후 접근 권한 활성화 진행합니다. 접근성 권한은 Hammerspoon이 키 입력, 창 제어, 앱 상태 확인 같은 작업을 수행하기 위해 필요한 권한입니다. 이 권한이 허용되지 않으면 단축키를 등록했더라도 일부 기능이 동작하지 않거나, 앱 제어 관련 코드가 정상적으로 실행되지 않을 수 있습니다.
사용법
Hammerspoon을 설치했다면 이제 설정 파일을 열고 Lua 스크립트를 입력해야 합니다. Hammerspoon의 기본 설정 파일은 사용자 홈 폴더 아래의 다음 위치에 있습니다.
~/.hammerspoon/init.lua이 파일은 Hammerspoon이 시작되거나 설정을 다시 불러올 때 실행되는 기본 설정 파일입니다. 공식 저장소에서도 Hammerspoon은 설치 직후 아무 동작도 하지 않으며, 사용자가 ~/.hammerspoon/init.lua 파일을 만들고 필요한 코드를 작성해야 한다고 안내하고 있습니다.
메뉴 막대의 Hammerspoon 아이콘 (1) 을 클릭한 뒤 (2) 를 선택합니다. init.lua 파일 (3) 이 열리면 이 파일에 원하는 스크립트를 입력합니다.
참고: init.lua 파일이 열리지 않거나 파일이 없는 경우에는 ~/.hammerspoon 폴더와 init.lua 파일을 직접 생성할 수 있습니다. 텍스트 편집기나 코드 편집기를 사용해 파일을 만든 뒤 저장하면 됩니다.
가장 기본적인 예제로 특정 단축키를 눌렀을 때 화면에 알림을 표시하도록 설정할 수 있습니다. init.lua 파일에 다음 코드를 입력합니다.
hs.hotkey.bind({"cmd", "option", "shift"}, "0", function()
hs.alert.show("Hello, World!")
end)위 코드는 cmd, option, shift 키를 누른 상태에서 0 키를 입력하면 화면에 Hello, World! 알림을 표시하는 예제입니다.
Hammerspoon의 hs.hotkey.bind 함수는 특정 키 조합과 실행할 동작을 연결할 때 사용합니다. 기본 구조는 다음과 같이 이해하면 됩니다.
- 첫 번째 값인
{"cmd", "option", "shift"}는 함께 누를 보조키 조합입니다. - 두 번째 값인
"0"은 보조키와 함께 누를 일반 키입니다. function()안에는 해당 단축키를 눌렀을 때 실행할 동작을 작성합니다.hs.alert.show("Hello, World!")는 화면에 간단한 알림 메시지를 표시하는 명령입니다.
Hammerspoon에서 보조키는 일반적으로 다음 이름을 사용합니다.
| 키 | 사용 가능한 이름 |
|---|---|
| Command | cmd, command |
| Control | ctrl, control |
| Option | alt, option |
| Shift | shift |
예제에서는 option을 사용했지만, 문서나 다른 예제에서는 alt로 표기된 경우도 많습니다. 두 이름은 같은 보조키를 의미하므로 편한 방식으로 사용하면 됩니다.
Hammerspoon 아이콘 (1) 클릭해 메뉴를 열고 (2) 클릭 하여 작성한 내용을 반영합니다.
이제 아무곳에서나 cmd + option + shift + 0 조합을 입력하면 Hello, World!라는 알림이 출력됩니다.
키 & 키코드 관련 기본 정보
일반적인 알파벳, 숫자 키를 제외한 키 정보 와 Apple script 키코드를 알고 있다면 작업을 진행 할때 편하게 사용할수 있습니다.
각각에 대해서 정리 합니다.
사용가능한 키 정리
Hammerspoon에서 자주 사용하는 키 이름은 다음과 같습니다. 키보드 종류나 macOS 입력 환경에 따라 일부 키는 동작 방식이 다를 수 있으므로, 처음에는 간단한 예제로 테스트한 뒤 실제 설정에 적용하는 것이 좋습니다.
| 구분 | 사용 가능한 키 |
|---|---|
| 기능키 | f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, f11, f12, f13, f14, f15, f16, f17, f18, f19, f20 |
| 숫자 패드 | pad, pad*, pad+, pad/, pad-, pad=, pad0, pad1, pad2, pad3, pad4, pad5, pad6, pad7, pad8, pad9, padclear, padenter |
| 기본 제어 키 | return, tab, space, delete, escape, help |
| 이동 키 | home, pageup, forwarddelete, end, pagedown, left, right, down, up |
| 보조 키 | shift, rightshift, cmd, rightcmd, alt, rightalt, ctrl, rightctrl |
| 기타 키 | capslock, fn |
AppleScript 키코드 정리
Hammerspoon은 Lua 스크립트를 통해 macOS 기능을 제어하는 도구입니다. 일반적인 단축키 등록은 Hammerspoon의 키 이름을 사용하면 되지만, 특정 앱에 키 입력을 보내거나 기존 AppleScript 예제를 참고해야 하는 경우에는 AppleScript 키코드나 macOS 키코드를 함께 알아두면 도움이 됩니다.
AppleScript 키코드는 특정 키를 숫자 코드로 지정할 때 사용합니다. 다만 Hammerspoon에서 단순 단축키를 등록하는 경우에는 대부분 키 이름을 그대로 사용하는 편이 더 읽기 쉽고 관리하기도 편합니다.
예를 들어 알림 표시, 앱 실행, 창 이동 같은 기본 자동화는 Hammerspoon의 API만으로 처리할 수 있습니다. 반면 특정 앱 내부 메뉴를 조작하거나, 앱이 제공하는 AppleScript 기능을 호출해야 하는 경우에는 hs.osascript.applescript 모듈을 사용할 수 있습니다.
바로가기: Complete list of AppleScript key codes (eastmanreference.com)처음 사용하는 단계에서는 AppleScript 키코드보다 Hammerspoon의 키 이름과 hs.hotkey.bind 구조를 먼저 익히는 것이 좋습니다. 이후 앱별 제어나 입력 소스 전환처럼 조금 더 구체적인 자동화가 필요할 때 키코드와 AppleScript를 함께 확인하면 됩니다.
FAQ
Hammerspoon은 macOS에서 AutoHotkey와 비슷한 목적의 자동화 도구로 사용할 수 있습니다. 다만 Windows의 AutoHotkey 코드를 그대로 옮겨 쓰는 방식이 아니라, macOS 환경에 맞게 Lua 스크립트로 새로 구성해야 합니다.
- AutoHotkey는 Windows 자동화에 특화된 도구이고, Hammerspoon은 macOS 자동화에 맞춰 만들어진 도구입니다.
- Hammerspoon에서는 단축키를 눌렀을 때 앱 실행, 창 이동, 알림 표시, 클립보드 처리 같은 동작을 연결할 수 있습니다.
- AutoHotkey처럼 키 조합과 실행 동작을 직접 지정할 수 있지만, 문법과 작성 방식은 Lua 기반으로 다릅니다.
- Windows와 macOS를 함께 사용하는 경우라면 완전히 같은 설정을 공유하기보다, 키보드 위치와 사용 습관을 기준으로 비슷한 동작을 맞추는 방식이 좋습니다.
- 단순 키 변경만 필요하다면 다른 키 매핑 도구가 더 편할 수 있고, 단축키를 기준으로 여러 macOS 동작을 연결하려면 Hammerspoon이 더 적합합니다.
Hammerspoon은 설치만으로 자동화 기능이 바로 실행되는 앱이 아닙니다. 사용자가 설정 파일에 코드를 작성하고, 해당 설정을 다시 불러와야 단축키가 동작합니다.
- 가장 먼저 확인할 부분은 설정 파일인 ~/.hammerspoon/init.lua가 실제로 만들어져 있는지입니다.
- init.lua 파일 안에 단축키 코드가 작성되어 있어야 하며, 파일을 저장한 뒤 Hammerspoon에서 Reload Config를 실행해야 합니다.
- macOS의 손쉬운 사용 권한이 허용되지 않으면 키 입력 감지나 앱 제어 기능이 제대로 동작하지 않을 수 있습니다.
- 이미 macOS나 다른 앱에서 사용 중인 단축키 조합이라면 Hammerspoon 단축키가 실행되지 않을 수 있습니다.
- 코드에 괄호, 따옴표, 쉼표 같은 문법 오류가 있어도 설정 전체가 정상적으로 적용되지 않을 수 있습니다.
- 문제가 계속된다면 먼저 Hello, World! 알림 예제처럼 단순한 코드로 동작 여부를 확인하는 것이 좋습니다.
Hammerspoon의 기본 설정 파일은 사용자 홈 폴더 아래의 ~/.hammerspoon/init.lua 경로에 만들어야 합니다. 이 파일은 Hammerspoon이 설정을 불러올 때 기본으로 읽는 Lua 스크립트 파일입니다.
- ~/.hammerspoon은 현재 사용자 홈 폴더 안에 있는 숨김 폴더입니다.
- init.lua는 Hammerspoon 설정의 시작점이 되는 파일입니다.
- 예를 들어 사용자 이름이 user라면 실제 경로는 /Users/user/.hammerspoon/init.lua 형태가 됩니다.
- Hammerspoon 메뉴에서 Open Config를 선택하면 일반적으로 이 파일을 열 수 있습니다.
- 파일이 없다면 .hammerspoon 폴더와 init.lua 파일을 직접 만들어 사용할 수 있습니다.
- iCloud Drive, 문서 폴더, 다운로드 폴더 등에 따로 저장한 init.lua 파일은 Hammerspoon이 자동으로 읽지 않습니다.
- 코드가 맞는데도 동작하지 않는다면 파일 내용보다 먼저 저장 위치를 확인하는 것이 좋습니다.
Hammerspoon 단축키가 동작하지 않을 때는 코드 문제만 보기보다 설정 파일, 권한, 단축키 충돌을 순서대로 확인하는 것이 좋습니다. 대부분의 문제는 이 세 가지 범위 안에서 발생합니다.
- 설정 파일 확인: init.lua 파일이 ~/.hammerspoon 경로에 있는지 확인합니다.
- 저장 여부 확인: 코드를 수정한 뒤 파일을 저장했는지 확인합니다.
- 설정 반영 확인: Hammerspoon 메뉴에서 Reload Config를 실행했는지 확인합니다.
- 접근 권한 확인: macOS 시스템 설정에서 Hammerspoon의 손쉬운 사용 권한이 허용되어 있는지 확인합니다.
- 단축키 충돌 확인: 같은 키 조합이 macOS 기본 단축키나 다른 앱에서 이미 사용 중인지 확인합니다.
- 문법 오류 확인: 괄호, 쉼표, 따옴표, end 누락처럼 Lua 문법 오류가 없는지 확인합니다.
- 테스트 단순화: 복잡한 코드를 잠시 제외하고 알림 표시 예제만 남겨 정상 동작 여부를 확인합니다.
Hammerspoon으로 macOS 입력 소스를 제어하는 방식의 한영 전환 자동화를 구성할 수 있습니다. 다만 입력 소스 이름과 macOS 설정 상태에 따라 코드가 달라질 수 있으므로, 기본 단축키 예제가 정상적으로 동작하는지 먼저 확인하는 것이 좋습니다.
- 특정 단축키를 눌렀을 때 한글 입력 소스로 전환하는 설정을 만들 수 있습니다.
- 다른 단축키를 눌렀을 때 영문 입력 소스로 전환하는 설정도 만들 수 있습니다.
- 한글과 영문 전환 실수가 잦은 경우, 토글 방식보다 각각의 입력 언어를 직접 지정하는 방식이 더 안정적일 수 있습니다.
- macOS에 등록된 입력 소스 이름이 무엇인지 확인해야 정확한 설정을 작성할 수 있습니다.
- 한국어 입력기가 2-Set Korean으로 표시되는지, 영문 입력기가 ABC로 표시되는지에 따라 코드 값이 달라질 수 있습니다.
- 입력 소스 전환 자동화가 동작하지 않는다면 먼저 Hammerspoon 단축키 자체가 정상적으로 실행되는지 확인해야 합니다.
- 여러 입력기를 함께 사용하는 환경에서는 원하는 입력 소스를 명확히 지정하는 것이 중요합니다.
Hammerspoon과 Karabiner-Elements는 모두 macOS 키보드 사용성을 개선할 때 자주 언급되지만, 목적이 다릅니다. 키 입력 자체를 바꾸는지, 단축키를 기준으로 macOS 동작을 실행하는지에 따라 선택 기준이 달라집니다.
- Karabiner-Elements는 키보드 입력 변경과 키 매핑에 적합합니다.
- 예를 들어 caps lock 키를 다른 키로 바꾸거나, 특정 키를 다른 키 입력으로 변환할 때 Karabiner-Elements가 편합니다.
- Hammerspoon은 단축키를 눌렀을 때 macOS 동작을 실행하는 자동화 설정에 적합합니다.
- 예를 들어 특정 단축키로 앱을 실행하거나, 창을 이동하거나, 알림을 띄우는 작업은 Hammerspoon이 다루기 좋습니다.
- 키보드 배열 자체를 바꾸고 싶다면 Karabiner-Elements를 먼저 검토하는 것이 좋습니다.
- 단축키와 앱, 창, 시스템 동작을 함께 연결하고 싶다면 Hammerspoon이 더 적합합니다.
- 두 도구를 함께 사용할 수도 있지만, 같은 키 조합을 동시에 처리하도록 설정하면 충돌할 수 있으므로 역할을 나누는 것이 좋습니다.
Hammerspoon은 처음부터 복잡한 자동화를 만들기보다, 설정 파일이 정상적으로 동작하는지 확인하는 단계부터 시작하는 것이 좋습니다. 기본 구조를 익힌 뒤 기능을 하나씩 추가하면 오류가 발생했을 때 원인을 찾기 쉽습니다.
- 먼저 Hammerspoon을 설치하고 메뉴 막대 아이콘이 표시되는지 확인합니다.
- macOS 시스템 설정에서 Hammerspoon의 손쉬운 사용 권한을 허용합니다.
- Open Config 메뉴를 통해 init.lua 파일을 열고 기본 예제를 입력합니다.
- Hello, World! 알림 예제를 실행해 단축키가 정상적으로 감지되는지 확인합니다.
- 그 다음 앱 실행 단축키처럼 결과가 바로 보이는 예제를 추가합니다.
- 단축키 구조와 function 작성 방식에 익숙해진 뒤 창 이동, 입력 소스 전환, 클립보드 처리 같은 기능으로 확장합니다.
- 코드를 한 번에 많이 붙여 넣기보다 하나씩 추가하고 Reload Config로 확인하는 방식이 안정적입니다.
- 설정이 복잡해지면 기능별로 주석을 남겨 두면 나중에 수정하기 쉽습니다.
마치며
Hammerspoon은 macOS에서 단축키와 자동화를 본인에게 맞게 구성하고 싶을 때 유용한 도구입니다. 설치 후 바로 기능이 제공되는 앱은 아니지만, init.lua 파일에 원하는 Lua 코드를 작성하면 기본 설정으로는 처리하기 어려운 동작까지 직접 구성할 수 있습니다. 특히 Windows에서 AutoHotkey를 사용해 본 경험이 있다면 macOS에서 비슷한 방식의 자동화 환경을 만드는 데 도움이 됩니다.
다만 Hammerspoon은 코드를 직접 입력해야 하므로 처음에는 약간의 적응 시간이 필요합니다. 처음부터 한영 전환, 창 관리, 앱별 자동화처럼 여러 기능을 한 번에 설정하기보다 단축키로 알림을 띄우는 간단한 예제부터 시작하는 것이 좋습니다. 설정이 정상적으로 적용되는 흐름을 이해한 뒤 필요한 기능을 하나씩 추가하면 관리하기도 쉽고 오류를 찾기도 편합니다.
또한 단축키 자동화 도구는 macOS 시스템 단축키나 다른 앱의 단축키와 충돌할 수 있습니다. 원하는 키 조합이 동작하지 않는다면 코드 문제만 의심하기보다 접근성 권한, Reload Config 실행 여부, 단축키 충돌 여부를 함께 확인해야 합니다. Hammerspoon은 한 번 설정 방식을 익히면 macOS 사용 환경을 본인에게 맞게 다듬는 데 꾸준히 활용할 수 있는 도구입니다.