skhd — Simple Hotkey Daemon for macOS

Introduction

skhd is a simple hotkey daemon for macOS that binds keyboard shortcuts to arbitrary shell commands. Created by the same developer behind the yabai tiling window manager, skhd is designed to be fast, lightweight, and scriptable. It reads keybindings from a plain text configuration file and runs as a background service.

What skhd Does

• Binds global keyboard shortcuts to any shell command or script
• Runs as a background daemon that starts at login
• Reads keybindings from a human-readable ~/.skhdrc configuration file
• Supports modifier keys (cmd, alt, shift, ctrl, fn) and key combinations
• Provides modal hotkey groups for context-dependent shortcuts

Architecture Overview

skhd hooks into the macOS accessibility API to intercept keyboard events system-wide. When a registered key combination is detected, it spawns a shell process to execute the bound command. The daemon parses the configuration file at startup and watches it for changes, reloading automatically when the file is modified. Its C implementation keeps memory usage and CPU overhead minimal.

Self-Hosting & Configuration

• Install via Homebrew: brew install koekeishiya/formulae/skhd
• Start the service: skhd --start-service
• Create ~/.skhdrc with one keybinding per line
• Grant Accessibility permissions in System Settings for skhd to intercept keys
• Reload configuration on the fly: skhd --reload

Key Features

• Sub-millisecond hotkey response with minimal resource consumption
• Plain-text configuration that is easy to version control with dotfiles
• Modal key layers for vim-style context switching between binding sets
• Automatic config reload when the .skhdrc file is saved
• Seamless integration with yabai for keyboard-driven tiling window management

Comparison with Similar Tools

• Hammerspoon — Lua-scriptable macOS automation with broader scope; skhd is focused purely on hotkeys and is faster
• Karabiner-Elements — key remapping and complex modifications; skhd binds keys to shell commands rather than remapping them
• BetterTouchTool — commercial tool with gesture and hotkey support; skhd is free, open source, and CLI-native
• Raycast — app launcher with hotkey triggers; skhd is a lower-level daemon without a GUI

FAQ

Q: Does skhd work with yabai? A: Yes. skhd is the recommended hotkey daemon for yabai. Most yabai users control window tiling entirely through skhd keybindings.

Q: Do I need to restart skhd after editing the config? A: No. skhd watches ~/.skhdrc and reloads automatically when the file changes. You can also force a reload with skhd --reload.

Q: Does skhd require Accessibility permissions? A: Yes. macOS requires Accessibility access for any app that intercepts global keyboard events.

Q: Can I define mode-based keybindings? A: Yes. skhd supports modal hotkey groups. You can define named modes and switch between them with a key combination, similar to vim's normal and insert modes.

Sources

• https://github.com/koekeishiya/skhd