skhd

Simple hotkey daemon for macOS

Visit WebsiteView Source
Category
Scripting
WM Type
—
License
free
Open Source
Yes
Keybindings
Yes
Scripting
Yes
Last Update
2025-12-09

Features

  • Hotkey daemon
  • Modal hotkeys
  • Process-specific
  • Shell integration
  • yabai companion

Install

$brew install asmvik/formulae/skhd

About

Simple, fast hotkey daemon. Often paired with yabai. Modal hotkeys, process-specific bindings.

Who It's For

skhd is for users who want a fast, reliable hotkey system that stays separate from their window manager. It's most commonly deployed alongside yabai: yabai manages window layout and skhd translates keystrokes into yabai -m commands. This separation of concerns means you can swap out either tool independently — use skhd with AeroSpace, use skhd to control any CLI tool, or replace skhd with a different hotkey daemon while keeping yabai. If you use any window manager that exposes a CLI, skhd is the recommended way to drive it from keyboard shortcuts.

How It Works

skhd reads a plain-text config file (~/.config/skhd/skhdrc) and registers global hotkey bindings at startup. Each binding maps a key combination to a shell command. Modal hotkeys work like tmux's prefix: press a key to enter a mode, then use simpler shortcuts within that mode. Process-specific bindings let the same key do different things in different apps — ctrl - h can mean "focus window west" globally, but pass through as a normal keystroke inside a terminal emulator.

# ~/.config/skhd/skhdrc

# Focus windows (yabai)
alt - h : yabai -m window --focus west
alt - l : yabai -m window --focus east
alt - j : yabai -m window --focus south
alt - k : yabai -m window --focus north

# Move windows
shift + alt - h : yabai -m window --warp west
shift + alt - l : yabai -m window --warp east

# Toggle float
alt - t : yabai -m window --toggle float

Compared to Similar Tools

Compared to Hammerspoon's hs.hotkey, skhd is narrower (hotkeys that run shell commands only) but faster to configure and more reliable for high-frequency key bindings. Hammerspoon is better when your hotkey needs to run complex multi-step Lua logic; skhd is better when you just need to invoke a CLI. skhd is made by the same author as yabai and is the canonical companion tool for it.

Requirements

  • macOS 11 Big Sur or later
  • Accessibility permission required for global key interception
  • Free and open-source (MIT license)

Getting Started

brew install asmvik/formulae/skhd
skhd --start-service
# Edit ~/.config/skhd/skhdrc
skhd --reload  # Apply config changes without restart

The yabai wiki at github.com/asmvik/yabai/wiki includes a recommended starter skhdrc that covers the most common yabai commands.

Discussion