# skhd — Simple Hotkey Daemon for macOS

> A fast, lightweight hotkey daemon for macOS that lets you bind keyboard shortcuts to shell commands and scripts using a simple configuration file.

## Install

Save in your project root:

# skhd — Simple Hotkey Daemon for macOS

## Quick Use
```bash
brew install koekeishiya/formulae/skhd
skhd --start-service
# Create ~/.skhdrc with your keybindings
echo "alt - return : open -a Terminal" >> ~/.skhdrc
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-34fd2072
Author: AI Open Source