skhd.zig

# SKHD in Zig

Simple Hotkey Daemon for macOS, ported from [skhd](https://github.com/koekeishiya/skhd) to Zig.

This implementation is **fully compatible with the original skhd configuration format** - your existing `.skhdrc` files will work without modification. Additionally, it includes new features like process groups and command definitions (`.define`) for cleaner configs, key forwarding/remapping, and improved error reporting.

📋 [View Changelog](CHANGELOG.md)

## v0.2.0 — Hotkey sequences

Bind a run of chords to one action, fired only when the chords arrive in order within a time budget (default 300ms, set with `.sequence_timeout`):

```bash
# Two quick Cmd-Q presses to quit Chrome; a single press does nothing.
cmd - q, cmd - q [
    "Google Chrome" | cmd - q
]
```

A shorter binding can also be the **prefix** of a longer sequence and fires when the sequence doesn't complete — like Vim's `timeoutlen`, but the wait only happens in apps where a longer match applies. That lets a global binding and an app's native shortcut share one chord:

```bash
lcmd - k : yabai -m window --focus north   # focus north — everywhere, instantly
cmd - k, cmd - k [
    "Google Chrome" | cmd - k              # …but double-tap sends Chrome its own Cmd-K
]
```

Every action form works on a sequence (commands, forwarding, unbound/passthrough, mode activation, process lists). See [SYNTAX.md](SYNTAX.md#hotkey-sequences) for the grammar and the [v0.2.0 CHANGELOG entry](CHANGELOG.md#020---2026-07-20).

## v0.1.0 — QMK-style keyboard remapping

skhd.zig now ships a system-level **grabber daemon** that enables remapping the user-session event tap can't reach. New directives:

- **`.remap caps_lock [device <alias>] : escape`** — instant 1:1 swap, applied via `hidutil` (no daemon).
- **`.remap key [device <alias>] { tap: …, hold: …, … }`** — tap vs. hold on the same key (e.g. `caps_lock` tapped = escape, held = control). Routed through `skhd-grabber` (root LaunchDaemon) which seizes the keyboard at the IOKit/HID level via Karabiner DriverKit. Required for caps-lock-class rules and modifier-as-hold rules that `hidutil` silently drops.
- **Layer holds** — `hold` can target a skhd mode instead of a key, so holding the source key activates the layer for the duration of the hold (e.g. hold `space` to enter `fn_layer`, where `fn_layer < 1 | f1` rebinds the number row to F-keys).
- **`.device <alias> { vendor: 0x…, product: 0x… }`** — scope rules to a specific keyboard, so one config does the right thing on each machine.

**Install** via Homebrew, or download the `.app` bundle from GitHub releases:

```bash
brew install jackielii/tap/skhd-zig
skhd --install-service
```

Or, manual install:

```bash
gh release download v0.1.0 --repo jackielii/skhd.zig --pattern '*-arm64-macos.tar.gz'
tar -xzf skhd-arm64-macos.tar.gz -C /tmp
sudo mv /tmp/skhd.app /Applications/
/Applications/skhd.app/Contents/MacOS/skhd --install-service
```

`--install-service` registers the agent, auto-installs th