automating-hammerspoon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hammerspoon 자동화

Hammerspoon 自动化

Hammerspoon 단축키, launchd 서비스, Ghostty 연동 가이드입니다.

本文是关于 Hammerspoon 快捷键、launchd 服务、Ghostty 集成的指南。

목적과 범위

目的与范围

macOS에서 Hammerspoon 자동화, launchd 연계, Ghostty 동작 이슈를 진단하고 복구하는 절차를 다룬다.

本文介绍 macOS 环境下 Hammerspoon 自动化、launchd 集成、Ghostty 运行问题的诊断与修复步骤。

핵심 절차

核心步骤

```
~/.hammerspoon/init.lua
```
와 LaunchAgent 상태를 함께 점검한다.
```
launchctl list
```
로 비정상 agent를 식별한다.
Ghostty 다중 인스턴스/단축키 문제를 재현 후 설정을 수정한다.
재로드 후 핵심 단축키 동작을 검증한다.

同时检查
```
~/.hammerspoon/init.lua
```
文件与 LaunchAgent 状态。
使用
```
launchctl list
```
命令识别异常 agent。
重现 Ghostty 多实例/快捷键问题后修改配置。
重载后验证核心快捷键的运行情况。

Known Issues

已知问题

darwin-rebuild 시 setupLaunchAgents 멈춤

launchd agent가 제대로 종료되지 않으면 멈출 수 있음
해결:
```
launchctl list | grep -v com.apple
```
확인 후 문제 agent 제거

한글 입력소스에서 Ctrl/Opt 단축키

macOS 기본 동작으로 한글 IME에서 Ctrl/Opt 키 조합이 동작 안 함
Hammerspoon에서 eventtap으로 강제 처리

Ghostty 새 인스턴스 문제

Ghostty 바이너리를 직접 실행하면 새 인스턴스로 열릴 수 있음 (Dock에 여러 아이콘)

해결: 실행 중이면

hs.application.get("Ghostty")

Cmd+N

, 미실행이면

open -a Ghostty

darwin-rebuild 时 setupLaunchAgents 卡住

如果 launchd agent 未正常终止，可能导致卡住
解决方法：执行
```
launchctl list | grep -v com.apple
```
检查后移除有问题的 agent

韩文输入法中的 Ctrl/Opt 快捷键

受 macOS 默认行为影响，韩文 IME 中 Ctrl/Opt 组合键无法正常工作
通过 Hammerspoon 的 eventtap 强制处理

Ghostty 新实例问题

直接运行 Ghostty 二进制文件会以新实例打开（Dock 中出现多个图标）
解决方法：若已运行，使用
```
hs.application.get("Ghostty")
```
+
```
Cmd+N
```
；若未运行，执行
```
open -a Ghostty
```

빠른 참조

快速参考

주요 단축키

主要快捷键

단축키	동작
`Ctrl+Option+Cmd+T`	Finder에서 현재 폴더로 Ghostty 열기
`Ctrl+;`	영어 입력으로 전환
`Cmd+Shift+Space`	영어 전환 후 Homerow 실행
`Ctrl+B`	영어 전환 후 tmux prefix 전달
`Ctrl+C/U/K/W/A/E/L/F`	Ghostty 전용 Ctrl 단축키 (CSI u 우회)
`Opt+B/F`	터미널 앱에서 단어 단위 이동

快捷键	操作
`Ctrl+Option+Cmd+T`	从 Finder 当前文件夹打开 Ghostty
`Ctrl+;`	切换至英文输入法
`Cmd+Shift+Space`	切换至英文后运行 Homerow
`Ctrl+B`	切换至英文后传递 tmux 前缀
`Ctrl+C/U/K/W/A/E/L/F`	Ghostty 专属 Ctrl 快捷键（绕过 CSI u）
`Opt+B/F`	在终端应用中按单词移动

설정 파일 위치

配置文件位置

파일	용도
`modules/darwin/programs/hammerspoon/default.nix`	Nix 모듈 (파일 배포 선언)
`modules/darwin/programs/hammerspoon/files/init.lua`	Hammerspoon 메인 설정 (소스)
`modules/darwin/programs/hammerspoon/files/foundation_remapping.lua`	Caps Lock → F18 리매핑 (소스)
`modules/darwin/programs/hammerspoon/files/atuin_menubar.lua`	Atuin 메뉴바 상태 표시 (소스)
`modules/darwin/programs/hammerspoon/files/ensure-chrome-autoconnect.sh`	Chrome DevTools MCP 자동연결 (소스)
`~/Library/LaunchAgents/`	launchd 사용자 에이전트

文件路径	用途
`modules/darwin/programs/hammerspoon/default.nix`	Nix 模块（文件部署声明）
`modules/darwin/programs/hammerspoon/files/init.lua`	Hammerspoon 主配置文件（源码）
`modules/darwin/programs/hammerspoon/files/foundation_remapping.lua`	Caps Lock → F18 重映射（源码）
`modules/darwin/programs/hammerspoon/files/atuin_menubar.lua`	Atuin 菜单栏状态显示（源码）
`modules/darwin/programs/hammerspoon/files/ensure-chrome-autoconnect.sh`	Chrome DevTools MCP 自动连接（源码）
`~/Library/LaunchAgents/`	launchd 用户代理目录

launchd 디버깅

launchd 调试

bash

undefined

bash

undefined

현재 로드된 에이전트 확인

查看当前已加载的代理

launchctl list | grep -v com.apple

특정 에이전트 상태

查看特定代理状态

launchctl list <label>

에이전트 언로드 (권장)

卸载代理（推荐方式）

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/<plist>

에이전트 로드 (권장)

加载代理（推荐方式）

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<plist>

레거시 명령 (deprecated, 호환용)

旧版命令（已废弃，仅兼容用）

launchctl unload ~/Library/LaunchAgents/<plist> launchctl load ~/Library/LaunchAgents/<plist>

undefined

launchctl unload ~/Library/LaunchAgents/<plist> launchctl load ~/Library/LaunchAgents/<plist>

undefined

자주 발생하는 문제

常见问题

darwin-rebuild 멈춤: launchd agent 충돌, 수동 언로드 필요
HOME이 /var/root: launchd 환경에서 HOME 미설정
open --args 무시: 이미 실행 중인 앱에 인수 전달 안 됨

darwin-rebuild 卡住：launchd 代理冲突，需手动卸载
HOME 路径为 /var/root：launchd 环境中未设置 HOME 变量
open --args 参数被忽略：无法向已运行的应用传递参数

레퍼런스

参考资料

트러블슈팅: references/troubleshooting.md
단축키 목록: references/hotkeys.md

故障排查：references/troubleshooting.md
快捷键列表：references/hotkeys.md