Hammerspoon 사용법 macOS 시스템 자동화 및 Lua 스크립트 설정 정리

macOS 운영체제를 사용하다 보면 반복적인 창 정렬이나 시스템 설정 변경을 위해 매번 마우스를 움직이는 과정이 작업의 흐름을 끊는 불편한 요소가 되곤 합니다. Hammerspoon 사용법을 익히면 이러한 반복 노력을 획기적으로 줄일 수 있으며, 단순한 단축키 지정을 넘어 macOS의 시스템 API를 직접 제어하는 강력한 자동화 환경을 구축할 수 있습니다.

필자의 경우 윈도우에서는 AutoHotkey를 활용해 업무 효율을 높여왔지만, macOS도 같이 사용하면서 이를 대체할 만한 도구를 찾는 데 꽤나 어려움을 겪기도 했는데요. 여러 대의 모니터를 오가며 창을 특정 위치에 배치하거나 네트워크 상태에 따라 설정을 바꾸는 등의 세밀한 제어가 일반적인 앱만으로는 원하는 대로 되지 않아 아쉬움이 있었습니다.

이런 점들이 불편하다면 Hammerspoon이 좋은 해결책이 될 수 있습니다. 익숙하지 않은 코드 작성 방식을 사용해야 한다는 점이 처음에는 불편할 수 있지만, 나만의 설정을 한번 만들어 두면 그 어떤 도구보다 업무 진행 간에 큰 도움이 됩니다. 맥 운영체제의 효율을 높여줄 수 있는 설치 방법부터 기본적인 예제들을 다음과 같이 정리합니다.

---

튜토리얼 환경: macOS Tahoe 26.4.1 (Apple Silicon), Hammerspoon 1.1.1v

개요

Hammerspoon은 예전에 유행하던 Moom이나 Slate 같은 창 관리 도구들이 가진 아쉬운 점들을 채워주기 위해 등장했습니다. 처음에는 단순히 창 위치를 옮겨주는 도구로 시작했지만, 지금은 맥의 내부 시스템과 긴밀하게 연결되어 마우스나 키보드 설정은 물론 오디오, 배터리, 와이파이 상태까지 본인이 원하는 대로 제어할 수 있는 전천후 도구로 자리 잡았다고 할 수 있습니다.

사용자는 init.lua라는 설정 파일에 원하는 동작을 코드로 작성하며 이 코드는 Hammerspoon 앱이 실행되는 동안 실시간으로 시스템 동작을 감시하고 실행합니다. 접근성 권한을 기반으로 작동하기 때문에 운영체제 동작까지 관여할 수 있는 것이 특징입니다. 여러 개발자들이 공유하는 일종의 확장 라이브러리라고 할 수 있는 다양한 Spoon을 통해 프로그램 경험이 많지 않은 사용자도 전문가가 만든 자동화 기능을 손쉽게 가져와 사용할 수 있습니다.

특징

Hammerspoon은 단순한 앱이라기보다 시스템 전체를 본인이 원하는 대로 설정할 수 있는 도구에 가깝습니다. Lua라는 가벼운 언어를 사용하기 때문에 컴퓨터에 무리를 주지 않으면서도 반응이 빠르고, 사용자가 어떻게 설정하느냐에 따라 활용할 수 있는 범위가 넓어지게 됩니다.

장점

Hammerspoon은 시스템 자원을 적게 소모하면서도 유료 자동화 도구보다 훨씬 높은 자유도를 제공한다는 점이 가장 큰 매력이라고 할 수 있습니다.

• 다양한 커스터마이징: 사용자가 Lua 스크립트를 직접 작성하므로 상용 소프트웨어가 지원하지 않는 독특한 자동화 로직을 생성할 수 있습니다.
• 경량화된 구조: 백그라운드에서 최소한의 메모리만 점유하며 작동하므로 시스템 성능에 미치는 영향이 매우 적고 응답 속도가 빠릅니다.
• 폭넓은 시스템 제어: 화면 밝기나 볼륨 조절은 물론, 창 위치 조정과 애플스크립트 실행 등 맥이 제공하는 거의 모든 내부 기능을 직접 제어할 수 있습니다.
• 활발한 커뮤니티: Spoon이라 불리는 플러그인 시스템을 통해 다른 사용자가 미리 만들어둔 유용한 스크립트 뭉치를 간편하게 설치하고 적용할 수 있습니다.

단점

맥의 시스템 설정을 세밀하게 만질 수 있는 만큼, 처음에 본인만의 환경을 구축하기까지는 어느 정도 공부와 적응 시간이 필요하기도 한데요.

• 코드 작성의 부담: 마우스로 클릭하는 설정 화면이 거의 없어서 모든 설정을 Lua 언어로 직접 작성해야 합니다. 프로그래밍이 낯선 사용자라면 처음에는 조금 어렵게 느껴질 수 있습니다.
• 초반 세팅의 번거로움: 앱을 처음 설치하면 빈 설정 파일만 있기 때문에, 기본적인 창 관리 기능을 하나 만드는 데에도 어느 정도의 학습이 필요합니다.
• 보안 권한 설정: 시스템의 핵심 기능을 건드리는 도구이다 보니, 접근성이나 화면 기록 권한처럼 예민한 부분을 허용해 주어야 하는 점을 고려해야 합니다.
• 오류 확인의 불편함: 코드를 작성하다 오타나 논리적 실수가 생기면 시스템 콘솔 로그를 직접 확인하며 문제를 찾아야 하는 번거로움이 있습니다.

설치

Hammerspoon은 공식 홈페이지에서 직접 다운로드하거나 터미널을 통한 패키지 관리 도구로 간단하게 설치할 수 있습니다. macOS 전용 도구이므로 설치 전 시스템 설정에서 접근성 권한을 허용하는 과정이 진행 되어야 합니다.

사용법

Hammerspoon의 모든 동작은 사용자 홈 디렉토리의 .hammerspoon 폴더 안에 있는 init.lua 파일을 기준으로 처리됩니다. Hammerspoon은 이 파일에 작성된 Lua 스크립트를 읽어 단축키, 앱 실행, 창 제어, 자동화 동작 등을 실행하는 방식으로 동작합니다.

설정 파일 열기

먼저 Hammerspoon 설정의 기준이 되는 init.lua 파일을 열어야 합니다. 이 파일은 일반적인 앱 환경설정 화면처럼 버튼을 눌러 값을 바꾸는 방식이 아니라, 직접 코드를 작성해 동작을 지정하는 설정 파일입니다. 처음 사용하는 경우에는 메뉴막대에서 제공하는 메뉴를 이용하는 것이 가장 간단합니다.

상단 메뉴막대에 위치한 Hammerspoon 아이콘 을 마우스로 클릭³해 메뉴 패널을 열고 Open Config 를 선택합니다.

기본 에디터로 init.lua 파일이 열리면 이곳에 필요한 스크립트를 추가하고 저장합니다. 설정 파일에는 Hammerspoon에서 사용할 단축키, 앱 실행, 창 배치, 자동화 코드 등을 순서대로 작성할 수 있습니다.

다만 코드를 저장했다고 해서 설정이 바로 반영되는 것은 아니기 때문에 Reload Config 메뉴로 설정을 다시 불러와야 동작하게 됩니다. Reload Config는 현재 init.lua 파일을 다시 읽어 적용하는 기능입니다.

Hammerspoon 메뉴에서 Console을 선택하면 설정 실행 결과와 오류 메시지를 확인할 수 있는 콘솔 창이 열립니다. init.lua 파일에 작성한 코드에 문제가 있거나 특정 API가 정상적으로 실행되지 않는 경우, 이 창에 관련 내용이 표시됩니다.

Console 창에서는 Hammerspoon이 설정 파일을 불러오는 과정에서 출력한 로그를 확인할 수 있습니다. 예를 들어 괄호 누락, 쉼표 오류, 잘못된 함수 이름, 권한 부족과 같은 문제가 있을 때 원인을 파악하는 데 도움이 됩니다. 특히 처음 설정을 구성하는 단계에서는 코드를 저장하고 Reload Config를 실행한 뒤 Console에 오류가 표시되는지 함께 확인하는 습관을 들이면 문제를 더 빠르게 찾을 수 있습니다.

기초 설정 및 창 관리

가장 먼저 특정 단축키를 눌렀을 때 터미널과 같은 앱이 실행되도록 설정하는 방법입니다.

hs.hotkey.bind({"cmd", "alt", "ctrl"}, "T", function()
    hs.application.launchOrFocus("Terminal")
end)

위 코드는 cmd, option, ctrl 키와 T를 동시에 누르면 터미널 앱을 실행하거나 이미 실행 중이라면 포커스를 맞춥니다. Shell and Termina 더 알아보기

hs.hotkey.bind({"alt", "ctrl"}, "Left", function()
    local win = hs.window.focusedWindow()
    local f = win:frame()
    local max = win:screen():frame()
    f.x = max.x
    f.y = max.y
    f.w = max.w / 2
    f.h = max.h
    win:setFrame(f)
end)

Hammerspoon으로 현재 활성화된 창을 화면 단축키를 통해 복잡한 마우스 드래그 없이도 창을 정확하게 이분할하여 배치할 수도 있습니다. 쉽게 말해 왼쪽 절반으로 즉시 정렬하는 스크립트이며 이를 응용하면 본인이 원하는 대로 창을 배치 할 수 있게 됩니다.

Hammerspoon 설정 자동 재로드

Hammerspoon 설정 파일을 수정한 뒤 변경 사항을 반영하려면 메뉴 막대의 Hammerspoon 아이콘에서 Reload Config를 수동으로 실행해야 합니다. 이 과정을 매번 직접 수행하는 대신, hs.pathwatcher와 hs.reload()를 함께 사용하면 설정 파일 변경 시 Hammerspoon 설정을 자동으로 다시 로드할 수 있습니다. 설정 폴더에 변경이 발생할 때마다 바로 설정을 다시 로드하려면 아래 코드를 사용할 수 있습니다.

hs.pathwatcher.new(os.getenv("HOME") .. "/.hammerspoon/", hs.reload):start()

위 코드를 init.lua에 추가하면 ~/.hammerspoon/ 폴더의 변경을 감지할 때마다 hs.reload()가 실행됩니다. 코드가 짧고 적용하기 쉽기 때문에 단일 설정 파일 위주로 Hammerspoon을 사용하는 경우 간단하게 적용할 수 있습니다.

다만 이 방식은 감시 대상 폴더 안에서 변경이 발생하면 바로 재로드를 시도합니다. 따라서 Lua 설정 파일이 아닌 파일을 수정하거나, 설정 폴더 안에 임시 파일이 생성되는 경우에도 재로드가 발생할 수 있습니다.

function reloadConfig(files)
	local doReload = false
	for _, file in ipairs(files) do
		if file:sub(-4) == ".lua" then
			doReload = true
		end
	end
	if doReload then
		hs.reload()
	end
end
myWatcher = hs.pathwatcher.new(os.getenv("HOME") .. "/.hammerspoon/", reloadConfig):start()

설정 폴더의 변경 사항 중 .lua 파일 변경이 있을 때만 설정을 다시 로드하려면 아래처럼 콜백 함수를 별도로 작성할 수 있습니다. 위 코드를 init.lua에 추가하면 myWatcher가 기본 설정 경로인 ~/.hammerspoon/ 폴더를 감시합니다. 변경이 감지되면 reloadConfig 함수가 변경된 파일 목록을 확인하고, 그중 .lua 파일이 포함되어 있을 때만 hs.reload()를 실행합니다.

이 방식은 init.lua만 사용하는 경우뿐 아니라 설정을 여러 Lua 파일로 나누어 관리하는 경우에도 적합합니다. 설정과 직접 관련 없는 파일 변경으로 인한 불필요한 재로드를 줄일 수 있어, Hammerspoon 설정을 점차 확장해 관리할 때 더 안정적으로 사용할 수 있습니다.

설정 파일 분할 로드

Hammerspoon의 설정이 복잡해질 경우, 하나의 init.lua 파일에 모든 코드를 넣기보다 기능별로 파일을 나누어 관리하는 것이 추후 유지보수에 유리합니다.

local modules = {
    "window_management",
    "hotkeys",
    "system_events"
}

기능별로 분리된 .lua 파일들을 메인 설정 파일에서 불러와 사용하는 방법입니다. require 문을 사용하면 기능별로 코드를 분리하여 관리할 수 있으며, pcall⁴을 결합해 특정 모듈의 오류가 전체 시스템의 중단으로 이어지지 않도록 방지할 수 있습니다.

for _, module in ipairs(modules) do
    local ok, err = pcall(require, module)
    if not ok then
        hs.alert.show("Error loading module: " .. module)
        print(err)
    end
end

먼저 불러올 파일들의 이름을 리스트 형태로 정의합니다. 각 파일은 ~/.hammerspoon/ 폴더 내에 window_management.lua와 같은 형태로 존재해야 합니다.

pcall과 require를 사용하여 각 모듈을 순차적으로 로드합니다. 로딩 중 오류가 발생하면 화면에 알림을 띄우고 콘솔에 에러 내용을 출력하여 문제를 쉽게 파악할 수 있게 돕습니다.

기타 예제 스크립트

Hammerspoon은 설정 자동 재로드 외에도 와이파이, 단축키, 애플리케이션 실행, 알림 등 macOS에서 발생하는 다양한 이벤트를 기준으로 자동화를 구성할 수 있습니다. hs.wifi.watcher는 와이파이 상태 변경 이벤트를 감지할 수 있으며, 기본적으로 SSID 변경을 감시합니다. hs.hotkey는 전역 단축키를 등록하는 기능을 제공합니다.

특정 와이파이에 연결되면 볼륨 조절

특정 와이파이에 연결되었을 때 자동으로 시스템 볼륨을 조절하는 방식입니다.

local wifiWatcher = hs.wifi.watcher.new(function()
	local network = hs.wifi.currentNetwork()

	if network == "Office_5G" then
		hs.audiodevice.defaultOutputDevice():setVolume(0)
	end
end):start()

위 코드는 현재 연결된 와이파이 이름이 Office_5G일 때 기본 출력 장치의 볼륨을 0으로 설정합니다. 사무실, 도서관, 회의실처럼 소리를 줄여야 하는 환경에서 사용할 수 있습니다.

특정 와이파이에 연결되면 알림 표시

와이파이 변경을 감지해 현재 네트워크에 맞는 알림을 표시할 수도 있습니다.

local wifiNotifyWatcher = hs.wifi.watcher.new(function()
	local network = hs.wifi.currentNetwork()

	if network == "Office_5G" then
		hs.notify.new({
			title = "Hammerspoon",
			informativeText = "사무실 와이파이에 연결되었습니다."
		}):send()
	end
end):start()

위 코드는 사무실 와이파이에 연결되면 macOS 알림을 표시합니다. 와이파이 변경을 기준으로 다른 자동화가 정상적으로 실행되는지 확인할 때도 간단한 테스트용으로 사용할 수 있습니다.

단축키로 자주 사용하는 앱 실행

Hammerspoon의 전역 단축키 기능을 사용하면 특정 키 조합으로 자주 사용하는 앱을 실행하거나 전환할 수 있습니다.

hs.hotkey.bind({"cmd", "alt"}, "T", function()
	hs.application.launchOrFocus("Terminal")
end)

위 코드는 cmd와 option 키를 누른 상태에서 T를 입력하면 Terminal 앱을 실행하거나, 이미 실행 중인 경우 해당 앱으로 전환합니다. 터미널, 브라우저, 메모 앱처럼 자주 사용하는 앱에 적용하기 적합합니다.

단축키로 화면 잠금 실행

단축키를 이용해 macOS 화면 잠금을 실행할 수도 있습니다.

hs.hotkey.bind({"cmd", "alt", "ctrl"}, "L", function()
	hs.caffeinate.lockScreen()
end)

위 코드는 cmd, option, ctrl 키를 누른 상태에서 L을 입력하면 화면 잠금을 실행합니다. 자리를 비울 때 메뉴를 직접 열지 않고 빠르게 화면을 잠글 수 있습니다.

단축키로 현재 시간 표시

간단한 알림 형태로 현재 시간을 표시할 수 있습니다.

hs.hotkey.bind({"cmd", "alt"}, "D", function()
	hs.alert.show(os.date("%Y-%m-%d %H:%M"))
end)

위 코드는 cmd와 option 키를 누른 상태에서 D를 입력하면 현재 날짜와 시간을 화면에 표시합니다. 복잡한 설정 없이 Hammerspoon 단축키와 Lua 기본 함수를 함께 사용하는 간단한 예제입니다.

참고: 이외에도 특정 언어전환을 특정 키로 지정하도록 수정하면 macOS에서 특정 키를 눌러 한영전환을 명시적으로 할 수도 있습니다. 관련 내용은 hammerspoon에서 한영전환 쉽게하는 방법 문서를 확인하세요.

FAQ

관련 글

• Scoop 사용법 Windows 환경 최적화를 위한 패키지 관리자
• UTM 네트워크 연결 모드 Bridge Host Only 변경하기
• macOS에서 Thorium 브라우저 설치하기
• UTM 가상 머신 스냅샷 클론 저장 또는 공유하기