skhd.zig

The .define directive allows you to create reusable command templates to reduce repetition in your skhd configuration. You can define simple commands without parameters or complex templates using positional placeholders.

Simple Commands

Use a colon : to define a command that takes no arguments. Reference it in a hotkey using the @ prefix.

Template Commands (with Placeholders)

Use {{n}} syntax to define positional placeholders (where n is the index starting at 1). When calling these templates in a hotkey, you must provide arguments enclosed in double quotes.

Rules for Templates

• Placeholder Numbering: Must start from 1 (e.g., {{1}}, {{2}}).
• Argument Quoting: All arguments passed to a template must be enclosed in double quotes (e.g., @cmd("arg")).
• Argument Count: You must provide exactly as many arguments as the highest placeholder number in the template.
• Escaping: Use \" to include a literal double quote inside a quoted argument.
• Reusability: The same placeholder can be used multiple times within a single definition.

# Simple definition
.define focus_recent : yabai -m window --focus recent
cmd - tab : @focus_recent

# Template definition
.define yabai_focus : yabai -m window --focus {{1}}
lcmd - h : @yabai_focus("west")

Aliases allow you to define reusable names for modifier combinations or single keys. They are expanded at parse time with zero runtime cost. Aliases must be defined before they are used, and redefinition is an error.

Modifier Aliases

• Defined with .alias $name <modifiers>.
• Must be used in the modifier position (before - or chained with +).
• Cannot be used as a key (e.g., ctrl - $hyper is an error).

Key Aliases

• Defined with .alias $name <key_or_hex>.
• Can use literal names (e.g., delete) or hex keycodes (e.g., 0x32).
• Must be used in the key position (after - or standalone).
• Cannot be used as a modifier (e.g., $grave - h is an error).

Note: You cannot bake modifiers into a single key alias (e.g., .alias $foo cmd - h is invalid). Instead, define the modifier and key separately and combine them at the use site.

# Modifier aliases
.alias $hyper cmd + alt + ctrl + shift
.alias $super cmd + alt

$hyper - h : echo "hyper-h"
$super + shift - h : echo "super+shift+h"

# Key aliases
.alias $grave 0x32
.alias $del delete

ctrl - $grave : open - a Notes
$del : echo plain-delete

A layer hold occurs when the hold attribute in a .remap block references a mode identifier instead of a hid_key. Holding the source key enters the mode; releasing it exits the mode.

1. Declare the mode: Use :: <name> @ to declare a mode. The @ (capture) flag determines if unbound keys in that layer leak through to the app or are absorbed.
2. Assign the mode to a key: In a .remap block, set hold : <mode_name>.
3. Define mode bindings: Use <mode_name> - <key> : <command> to define what happens while the layer is active.

Layer-hold modes are evaluated on the agent's run loop via IPC messages from the grabber.

# 1. Declare a capture-mode
:: fn_layer @

# 2. Hold space to enter fn_layer
.remap space [device builtin] {
    tap             : space
    hold            : fn_layer
    timeout         : 200ms
    retro_tap       : on
}

# 3. Define bindings for the layer
fn_layer < 1 | f1
fn_layer < 2 | f2
fn_layer < tab | alt - tab

The skhd.zig configuration syntax is fully compatible with the original skhd syntax. It uses a grammar based on modes, hotkeys (triggers), and actions.

Core Components:

• Modes: Named contexts that group hotkeys. Modes can be chained (e.g., mode1, mode2).
• Triggers: A sequence of chords (keysyms). A chord is a combination of modifiers and a key.
• Actions: What happens when a trigger is activated. Actions include executing shell commands, switching modes, or passing keypresses through.
• Process Lists: Scoped bindings that apply only to specific applications or process groups.

Key Syntax Symbols:

• : or |: Execute a command.
• ->: Passthrough (the keypress is not consumed by skhd).
• ~: Unbound (the keypress is forwarded per usual).
• ;: Activate a mode.
• [ ]: Define a process list for application-specific scoping.

hotkey       = <mode> '<' <action> | <action>
mode         = 'name of mode' | <mode> ',' <mode>
action       = <trigger> '[' <proc_map_lst> ']'   | <trigger> '->' '[' <proc_map_lst> ']'
               <trigger> ':' <command>            | <trigger> '->' ':' <command>
               <trigger> ';' <mode_activation>    | <trigger> '->' ';' <mode_activation>
               <trigger> '~'
trigger      = <keysym> | <keysym> ',' <keysym> (',' <keysym>)*
keysym       = <mod> '-' <key> | <key>
mod          = 'modifier keyword' | <mod> '+' <mod>
key          = <literal> | <keycode>

The project uses a split-binary architecture to handle different permission levels required by macOS:

1. skhd (User Agent): Runs as your local user. It handles standard hotkeys, modes, and non-caps .remap rules using hidutil or CGEventTap. If your configuration contains caps_lock tap-hold rules (caps-class .remap {}), the agent automatically attempts to connect to the grabber via a Unix socket.

2. skhd-grabber (System Daemon): Runs as root. It is responsible for seizing HID devices (using IOHIDDeviceOpen with kIOHIDOptionsTypeSeizeDevice) to enable tap-hold behavior for keys like caps_lock. It processes the raw HID stream and injects resulting key events through the Karabiner virtual HID device (vhidd).

Key Behaviors:

• Configuration: The user agent (skhd) owns the configuration file (~/.config/skhd/skhdrc). It parses the file and sends only the relevant caps-class rules to the grabber.
• User Switching: The grabber tracks the console user. When you switch users, the grabber applies the rules for the new active user and releases the seize on devices if no rules are active for that user.
• Coexistence: If Karabiner-Elements is already seizing a device, skhd-grabber will fail to seize it and log a warning. The first seizer wins.