### Build and Install SKHD from Source

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

Use these commands to build SKHD from source, create a signed application bundle, and install it as a service. Ensure you have Zig installed and the necessary signing tools.

```bash
zig build sign-app
ln -sfn "$(pwd)/zig-out/skhd.app" /Applications/skhd.app
/Applications/skhd.app/Contents/MacOS/skhd --install-service
/Applications/skhd.app/Contents/MacOS/skhd --start-service
```

--------------------------------

### Install SKHD via Homebrew

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Installs SKHD and registers its service using Homebrew. This is the recommended installation method.

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

--------------------------------

### Install and Manage skhd Service

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Use these commands to install, start, stop, restart, check the status, and uninstall the skhd service. The service automatically starts on login and reloads on config changes.

```bash
# Install and start the service
skhd --install-service
skhd --start-service
```

```bash
# Check if skhd is running properly
skhd --status
```

```bash
# Restart service (useful for restarting after giving accessibility permissions)
skhd --restart-service
```

```bash
# Stop service
skhd --stop-service
```

```bash
# Uninstall service
skhd --uninstall-service
```

--------------------------------

### Install skhd.zig with Homebrew

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Use this command to install skhd.zig via Homebrew. This is the simplest installation method.

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

--------------------------------

### Install Karabiner DriverKit extension

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Downloads and installs the Karabiner DriverKit .pkg and writes the VHIDD daemon launchd plist. This command is used to install the necessary extension ahead of time or if the agent's install flow does not handle it.

```bash
skhd --install-dext     # downloads + installs the pkg, writes the
                        # VHIDD daemon launchd plist (or skips if
                        # Karabiner-Elements is already handling it)
```

--------------------------------

### SKHD Configuration Example

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

A sample SKHD configuration file demonstrating device declaration, tap-hold key remapping for caps_lock, and layer activation with spacebar. This example requires replacing placeholder vendor and product IDs with actual values.

```bash
# 1. Declare the keyboard you want to remap.
.device builtin { vendor: 0x05AC, product: 0x0342 }

# 2. caps_lock acts like ctrl when held, escape when tapped.
.remap caps_lock [device builtin] {
    tap             : escape
    hold            : lctrl
    timeout         : 120ms
    permissive_hold : on
}

# 3. Hold space to enter a "function layer", release to exit.
:: fn_layer @
.remap space [device builtin] {
    tap             : space
    hold            : fn_layer
    timeout         : 200ms
    retro_tap       : on
}

# 4. While the layer is held, number row → F-row.
fn_layer < 1 | f1
fn_layer < 2 | f2
fn_layer < 3 | f3
# … etc
```

--------------------------------

### Install skhd.zig from Pre-built Binaries

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Extract and install skhd.zig from a pre-built tarball. Ensure you use the correct tarball for your architecture (Apple Silicon or Intel).

```bash
tar -xzf skhd-arm64-macos.tar.gz   # or skhd-x86_64-macos.tar.gz on Intel
mv skhd.app /Applications/
# Optional: expose the CLI on your PATH
sudo ln -sfn /Applications/skhd.app/Contents/MacOS/skhd /usr/local/bin/skhd
```

--------------------------------

### Install Grabber Script Logic

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/PLAN_GRABBER.md

This outlines the steps involved in installing the skhd grabber, including checking for dependencies, escalating privileges, copying the binary, and setting up the launch daemon.

```bash
skhd --install-grabber:
1. Check `systemextensionsctl list` for `org.pqrs.Karabiner-DriverKit-VirtualHIDDevice`. If absent, print install link, abort.
2. Sudo-escalate (or instruct user to re-run with sudo).
3. Copy `skhd-grabber` binary to `/usr/local/libexec/skhd-grabber`.
4. Write `/Library/LaunchDaemons/com.jackielii.skhd.grabber.plist`
   with `RunAtLoad=true`, `KeepAlive=true`, `ProcessType=Interactive`.
5. `launchctl bootstrap system /Library/LaunchDaemons/...`.
6. Verify daemon is running and reachable on the socket.
```

--------------------------------

### Build skhd.zig from Source

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Clone the repository, build the .app bundle with code-signing, and install it. This method is recommended for development and ensures accessibility permissions persist.

```bash
# Clone the repository
git clone https://github.com/jackielii/skhd.zig
cd skhd.zig

# Build the .app bundle and code-sign it
# (required for Accessibility to persist on macOS Tahoe / Sequoia)
zig build sign-app -Doptimize=ReleaseFast

# Install: symlink the bundle into /Applications, expose the CLI
ln -sfn "$(pwd)/zig-out/skhd.app" /Applications/skhd.app
sudo ln -sfn /Applications/skhd.app/Contents/MacOS/skhd /usr/local/bin/skhd
```

--------------------------------

### Manual SKHD Installation

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Installs SKHD manually by downloading the release, extracting it, and then installing the service. This method requires using `sudo` for moving the application and installing the service.

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

--------------------------------

### Start the new skhd service

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

Start the upgraded skhd service. Monitor the log file for confirmation of successful startup.

```bash
skhd --start-service
```

--------------------------------

### SKHD Mode Activation Examples

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Examples demonstrating how to activate modes in skhd. Mode activation can include an optional command to execute upon switching.

```plaintext
mode_activation = <mode> | <mode> ':' <command>
```

```plaintext
cmd - w ; window
```

```plaintext
cmd - w ; window : echo "Window mode"
```

```plaintext
escape ; default
```

```plaintext
cmd - w ; window
```

```plaintext
"terminal" ; vim_mode
```

```plaintext
@browsers ; browser_mode
```

--------------------------------

### Install the new skhd LaunchAgent plist

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

Install the new service plist file, which points to the stable symlink for the skhd.app.

```bash
skhd --install-service
```

--------------------------------

### Install skhd.zig from GitHub Actions Development Builds

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Download and install a development build from GitHub Actions. This method is for Apple Silicon and requires unzipping the artifact and then extracting the tarball.

```bash
unzip skhd-ReleaseFast.zip
tar -xzf skhd-arm64-macos.tar.gz
mv skhd.app /Applications/
sudo ln -sfn /Applications/skhd.app/Contents/MacOS/skhd /usr/local/bin/skhd
```

--------------------------------

### Install skhd grabber manually

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Installs the skhd grabber system daemon manually using sudo. This command is useful if the prompt did not fire during the initial service installation or if rules were added later.

```bash
sudo skhd --install-grabber
```

--------------------------------

### Application Launching Hotkeys

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Set up hotkeys to launch specific applications. For example, 'alt + return' to open Terminal and 'alt + b' to open Safari.

```bash
alt - return : open -a Terminal
alt - b : open -a Safari
```

--------------------------------

### Local Debug Workflow Setup

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/CODE_SIGNING.md

Builds and signs a separate development bundle for debugging. This ensures debug runs have their own TCC slot, distinct from the production bundle.

```bash
# To override the dev cert/bundle ID, set SKHD_CERT and SKHD_BUNDLE_ID before invoking scripts/codesign.sh directly.
```

--------------------------------

### Modal Window Management with Visual Indicators

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Configure a modal workflow for window management using AnyBar for visual feedback. This setup allows for distinct modes for focusing, moving, warping, and stacking windows, with visual cues indicating the active mode.

```bash
# Window management mode with anybar visual indicator
# Install anybar: brew install --cask anybar

# Define window management mode for warp/stack operations
# Use anybar to indicate the mode: https://github.com/tonsky/AnyBar
:: winmode @ : echo -n "red" | nc -4u -w0 localhost 1738
:: default : echo -n "hollow" | nc -4u -w0 localhost 1738

# Enter window mode with meh + m (shift + alt + ctrl + m)
meh - w ; winmode
winmode < escape ; default
winmode < meh - w ; default

# Alternative: Enter window mode AND show notification (New in skhd.zig!)
# This executes the command when switching to the mode
# It allows for different commands to execute and switch to another mode
meh - w ; winmode : osascript -e 'display notification "Window mode active" with title "skhd"'
winmode < escape ; default : osascript -e 'display notification "Normal mode" with title "skhd"'

# Focus operations - basic hjkl for focus
winmode < h : yabai -m window --focus west || yabai -m display --focus west
winmode < j : yabai -m window --focus south || yabai -m display --focus south
winmode < k : yabai -m window --focus north || yabai -m display --focus north
winmode < l : yabai -m window --focus east || yabai -m display --focus east

# Move operations - shift + hjkl for moving
winmode < shift - h : yabai -m window --move rel:-80:0
winmode < shift - j : yabai -m window --move rel:0:80
winmode < shift - k : yabai -m window --move rel:0:-80
winmode < shift - l : yabai -m window --move rel:80:0

# Warp operations - alt + shift + hjkl for warping
winmode < alt + shift - h : yabai -m window --warp west
winmode < alt + shift - j : yabai -m window --warp south
winmode < alt + shift - k : yabai -m window --warp north
winmode < alt + shift - l : yabai -m window --warp east

# Stack operations - ctrl + shift + hjkl for stacking
winmode < ctrl + shift - h : yabai -m window --stack west
winmode < ctrl + shift - j : yabai -m window --stack south
winmode < ctrl + shift - k : yabai -m window --stack north
winmode < ctrl + shift - l : yabai -m window --stack east

# Stack management shortcuts
winmode < s : yabai -m window --insert stack  # Toggle stack mode
winmode < u : yabai -m window --toggle float; yabai -m window --toggle float  # Unstack window
winmode < n : yabai -m window --focus stack.next  # Navigate stack next
winmode < p : yabai -m window --focus stack.prev  # Navigate stack prev

# Resize submode
winmode < r ; resize
:: resize @ : echo -n "orange" | nc -4u -w0 localhost 1738
resize < h : yabai -m window --resize left:-20:0
resize < j : yabai -m window --resize bottom:0:20
resize < k : yabai -m window --resize top:0:-20
resize < l : yabai -m window --resize right:20:0
resize < escape ; winmode
```

--------------------------------

### Application Launching and Toggling

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Configure shortcuts for launching applications directly or toggling them using skhd.zig's custom command definitions. Includes examples for traditional app launching and managing scratchpad applications.

```bash
# Quick app launching (traditional way)
alt - return : open -a Terminal
alt - b : open -a Safari

# Toggle apps using command definitions (New in skhd.zig!)
alt - f : @toggle_app("Finder")
alt - c : @toggle_app("Visual Studio Code")

# Scratchpad apps with yabai (New in skhd.zig!)
# In yabairc: yabai -m rule --add app="^YouTube Music$" scratchpad=music grid=11:11:1:1:9:9
alt - m : @toggle_scratchpad("music", "YouTube Music")
alt - n : @toggle_scratchpad("notes", "Notes")
```

--------------------------------

### skhd.zig Key Forwarding/Remapping

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Shows examples of key forwarding and remapping in skhd.zig, including layout fixes, function key navigation, and preserving default key behavior.

```bash
# Keyboard layout fixes
0xa | 0x32             # UK keyboard § to `
shift - 0xa | shift - 0x32  # shift - § to ~

# Function key navigation (for laptop keyboards)
fn - j | down
fn - k | up
fn - h | left
fn - l | right

# When you have cmd - number for yabai spaces,
# and you still want the cmd - number to work in applications
ctrl - 1 | cmd - 1
ctrl - 2 | cmd - 2
ctrl - 3 | cmd - 3
```

--------------------------------

### Manual Recovery for skhd.zig Upgrade Issues

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

If issues arise after a brew upgrade, run this command to manually start the service and verify its status. This is idempotent and performs the same action as the post-install hook.

```bash
skhd --start-service   # idempotent — same as what post_install just ran
skhd --status          # verify
```

--------------------------------

### Run Grabber Daemon with Logging

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Runs the grabber daemon from the current checkout, requiring sudo privileges. If an installed LaunchDaemon is active, it must be stopped first to avoid IPC socket conflicts.

```bash
# Run the grabber daemon from this checkout. Requires sudo. If
# `skhd --install-grabber` was run, stop the installed LaunchDaemon
# first or it will hold the IPC socket:
#     sudo launchctl bootout system/com.jackielii.skhd.grabber
zig build run-grabber 2>&1 | tee /tmp/skhd-grabber.log
```

--------------------------------

### skhd-grabber CLI Commands

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/PLAN_GRABBER.md

Commands to install, uninstall, and check the status of the skhd-grabber system daemon. These commands are used to manage the grabber's integration with the system.

```bash
skhd --install-grabber
```

```bash
skhd --uninstall-grabber
```

```bash
skhd --grabber-status
```

--------------------------------

### Conditional Keybindings for Native Apps

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Configure keybindings that apply conditionally. This example uses 'home' to send 'cmd + left' to native applications, but 'alt + left' to others.

```bash
# Line start/end
home [
    @native_apps ~
    *            | cmd - left
]
```

--------------------------------

### Karabiner-Elements Device Filtering Configuration

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/PLAN_ADVANCED_FEATURES.md

Example JSON configuration for device-specific hotkey filtering in Karabiner-Elements. It uses vendor_id and product_id to identify devices.

```json
{
    "conditions": [{
        "type": "device_if",
        "identifiers": [{
            "vendor_id": 1452,
            "product_id": 834,
            "description": "Apple Internal Keyboard"
        }]
    }]
}
```

--------------------------------

### skhd.zig Special Keys

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Provides examples of special keys that can be used in skhd.zig hotkey definitions, including navigation keys, function keys, and media keys.

```bash
# Navigation keys
cmd - left : echo "Left arrow"
cmd - right : echo "Right arrow"
cmd - up : echo "Up arrow"
cmd - down : echo "Down arrow"

# Special keys
cmd - space : echo "Space"
cmd - return : echo "Return/Enter"
cmd - tab : echo "Tab"
cmd - escape : echo "Escape"
cmd - delete : echo "Delete/Backspace"
cmd - home : echo "Home"
cmd - end : echo "End"
cmd - pageup : echo "Page Up"
cmd - pagedown : echo "Page Down"

# Function keys
cmd - f1 : echo "F1"
cmd - f12 : echo "F12"

# Media keys
sound_up : echo "Volume Up"
sound_down : echo "Volume Down"
mute : echo "Mute"
brightness_up : echo "Brightness Up"
brightness_down : echo "Brightness Down"
```

--------------------------------

### Upgrade skhd-zig via Homebrew

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

Use Homebrew to upgrade the skhd-zig formula to the latest version. This installs the new .app bundle and symlinks the CLI.

```bash
brew upgrade jackielii/tap/skhd-zig
```

--------------------------------

### Create Self-Signed Certificate

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/CODE_SIGNING.md

Manually create a self-signed code signing certificate named 'skhd-cert' in Keychain Access. This is a one-time setup required if automatic creation fails.

```bash
open "/Applications/Utilities/Keychain Access.app"
```

--------------------------------

### Conditional Keybindings for Terminal Apps

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Configure keybindings that apply conditionally. This example uses 'ctrl + left' to send 'alt + left' to terminal applications, but 'cmd + left' to others.

```bash
# Word movement
ctrl - left [
    @terminal_apps ~
    *              | alt - left
]
```

--------------------------------

### Build and Run with Info Logs (ReleaseSafe)

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Build skhd in `ReleaseSafe` mode and run it with the `-V` flag to enable info logs. This provides a production-shaped binary with more verbose logging than the default Homebrew build.

```bash
zig build -Doptimize=ReleaseSafe && \
    ./zig-out/bin/skhd -V
```

--------------------------------

### skhd.zig Process-Specific Bindings

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Demonstrates how to define different commands for specific applications using process-specific bindings in skhd.zig.

```bash
# Different commands for different applications
cmd - n [
    "terminal" : echo "New terminal window"
    "safari"   : echo "New safari window"
    "finder"   : echo "New finder window"
    *          : echo "New window in other apps"
]
```

--------------------------------

### Build and Sign Application

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/CODE_SIGNING.md

Commands to build the application. 'zig build' creates the bare binary, while 'zig build sign-app' builds the .app bundle and signs both the inner Mach-O and the bundle.

```bash
zig build
```

```bash
zig build sign-app
```

```bash
# Equivalent to:
zig build app                          # produces zig-out/skhd.app
./scripts/codesign.sh zig-out/skhd.app # signs both layers
```

--------------------------------

### Uninstall skhd Services

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Uninstall the skhd agent and grabber using the provided commands. The DriverKit dext from Karabiner-Elements will remain installed.

```bash
skhd --uninstall-service
```

```bash
sudo skhd --uninstall-grabber
```

--------------------------------

### Disable Karabiner Grabber

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

If Karabiner-Elements is installed and causing conflicts, disable its grabber using `launchctl bootout`. This command is for temporary disabling.

```bash
sudo launchctl bootout system/org.pqrs.service.daemon.karabiner_grabber
```

--------------------------------

### Build skhd.zig Project

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Build the project to create an executable. Use optimization flags for release builds.

```bash
# Build the project (creates executable in zig-out/bin/)
zig build
```

```bash
# Build in release mode with optimizations
zig build -Doptimize=ReleaseFast
```

--------------------------------

### Modal System Activation and Commands

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Sets up a modal system where specific key combinations activate a mode, and other key combinations perform actions within that mode. This allows for context-dependent shortcuts.

```bash
# Declare mode
:: window : echo "Window mode"

# Enter mode
cmd - w ; window

# Enter mode and execute command
cmd - w ; window : echo "Switching to window mode"

# Commands in mode
window < h : yabai -m window --focus west
window < escape ; default : echo "Returning to default mode"
```

--------------------------------

### skhd startup log with retries

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

Log output indicating that the event tap creation failed initially but was handled by the new retry mechanism.

```text
warning(event_tap): Event tap creation failed (attempt 1/10), retrying in 500ms...
info(event_tap): Event tap created on attempt 2/10
```

--------------------------------

### Build the skhd.zig Project

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Builds the project, creating an executable in the zig-out/bin/ directory. This is the primary command for compiling the daemon.

```bash
# Build the project (creates executable in zig-out/bin/)
zig build
```

--------------------------------

### Run skhd.zig Benchmarks

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Runs the project's benchmarks using the ReleaseFast build configuration.

```bash
# Run benchmarks (ReleaseFast)
zig build bench
```

--------------------------------

### Activate Edit Mode for Specific Applications

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Use 'cmd - e' to activate an edit mode for specific applications. This example shows how to display a notification for VS Code and Xcode, with a fallback for other applications.

```bash
cmd - e [
    "code" ; edit_mode : osascript -e 'display notification "Edit mode for VS Code"'
    "xcode" ; edit_mode : osascript -e 'display notification "Edit mode for Xcode"'
    * : echo "No special mode for this app"
]
```

--------------------------------

### skhd.zig Basic Hotkey Syntax

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Illustrates the fundamental syntax for defining hotkeys in skhd.zig, showing basic modifier-key combinations and their associated commands.

```bash
# Basic format: modifier - key : command
cmd - a : echo "Command+A pressed"

# Multiple modifiers
cmd + shift - t : open -a Terminal

# Different modifier combinations
ctrl - h : echo "Control+H"
alt - space : echo "Alt+Space"
shift - f1 : echo "Shift+F1"
```

--------------------------------

### Profile skhd Performance (ReleaseSafe)

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Build skhd in `ReleaseSafe` mode and run it with the `-P` flag for performance profiling. This provides a profile closer to production behavior.

```bash
zig build -Doptimize=ReleaseSafe && \
    ./zig-out/bin/skhd -P
```

--------------------------------

### Test Key Combinations in Observe Mode

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Run the application in observe mode to test key combinations and their corresponding hex codes.

```bash
zig build run -- -o
```

--------------------------------

### Remap Keys using .remap colon form in skhd.zig

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Perform instant 1:1 key swaps using the .remap colon form, which applies mappings via hidutil's UserKeyMapping table. This method does not require a daemon and works without installing skhd-grabber.

```bash
# UK ISO MacBook: map § (top-left key, HID-named non_us_backslash) to
# the ISO grave key so it types `.
.remap non_us_backslash [device builtin] : grave

# Swap caps_lock with escape on an external keyboard.
.remap caps_lock [device keychron] : escape
```

--------------------------------

### Run Tests

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Execute all unit and integration tests for the project. This command should be run after any implementation to ensure tests pass.

```bash
zig build test
```

--------------------------------

### Unified Logging Capture

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Use the `log show` command to capture logs from both `skhd` and `skhd-grabber` processes for a 5-minute window.

```bash
log show --last 5m --predicate 'process == "skhd" OR process == "skhd-grabber"'
```

--------------------------------

### Device-Aware Remapping (Block Form - Tap/Hold)

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Configure tap-hold semantics for keys using the block form. This requires skhd-grabber as hidutil cannot distinguish between tap and hold. Examples include remapping Caps Lock to Escape (tap) or Control (hold), and Space to Space (tap) or Fn layer (hold).

```bash
.remap caps_lock [device builtin] {
    tap             : escape
    hold            : lctrl
    timeout         : 120ms
    permissive_hold : on
    retro_tap       : off
}

.remap space [device builtin] {
    tap             : space
    hold            : fn_layer
    timeout         : 200ms
    permissive_hold : on
    retro_tap       : on
}
```

--------------------------------

### Successful skhd startup log

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

Expected log output upon successful startup of the skhd service.

```text
info(skhd): Starting event tap
info(skhd): Event tap created successfully. skhd is now running.
```

--------------------------------

### Run skhd.zig Application

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Run the application directly or with specific arguments and configuration files.

```bash
# Run the application
zig build run
```

```bash
# Run with arguments
zig build run -- -V -c ~/.config/skhd/skhdrc
```

--------------------------------

### Define and Use Window Resizing Command

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/command-definitions.md

Define a command for resizing windows using multiple parameters for direction and amount. Ensure arguments are correctly quoted.

```shell
# Define resize command with multiple parameters
.define resize_win : yabai -m window --resize {{1}}:{{2}}:{{3}}
```

```shell
# Use with different resize operations
cmd + ctrl + shift - k : @resize_win("top", "0", "-10")
cmd + ctrl + shift - j : @resize_win("bottom", "0", "10")
cmd + ctrl + shift - h : @resize_win("left", "-10", "0")
cmd + ctrl + shift - l : @resize_win("right", "10", "0")
```

--------------------------------

### Run skhd.zig Tests

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Executes the project's tests. This command is recommended for testing as single-file `zig test` is no longer supported for module tests requiring build options.

```bash
# Run tests (use this — single-file `zig test` no longer works since
# module tests now need build_options / grabber_protocol / plist imports)
zig build test
```

--------------------------------

### Global Vim-like Navigation

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Configure global hotkeys for Vim-like navigation (h, j, k, l) to focus windows in different directions (west, south, north, east).

```bash
# Global navigation
cmd - h : focus west
cmd - j : focus south
cmd - k : focus north
cmd - l : focus east
```

--------------------------------

### Run skhd.zig Tests (No Progress)

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Executes the project's tests without displaying progress indicators. Use this command if the standard test command hangs.

```bash
ZIG_PROGRESS=0 zig build test   # if it hangs
```

--------------------------------

### Verbose Logging for Config Issues

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Run the application with verbose logging enabled to troubleshoot configuration-related problems.

```bash
zig build run -- -V
```

--------------------------------

### List Available Signing Identities

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/CODE_SIGNING.md

List all available code signing identities on your system. Use this to verify that your signing certificate exists before running the `zig build sign` command.

```bash
security find-identity -v -p codesigning
```

--------------------------------

### Mode-based Workflow for Resizing

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Define a 'resize' mode that can be activated and then used with directional keys to resize windows. Includes a way to exit the mode back to default.

```bash
:: resize @ : echo "Resize mode"
cmd - r ; resize
resize < h : resize left
resize < l : resize right
resize < escape ; default
```

--------------------------------

### Run skhd.zig Tests

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Execute the project's tests to ensure functionality.

```bash
# Run tests
zig build test
```

--------------------------------

### Enable skhd in launchd if disabled

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

If the previous command showed skhd as 'disabled', run this command to re-enable it.

```bash
launchctl enable gui/$(id -u)/com.jackielii.skhd
```

--------------------------------

### Karabiner-Elements Virtual HID Driver Approach

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/PLAN_ADVANCED_FEATURES.md

Illustrates the use of a virtual HID driver for input event manipulation, offering complete control but requiring kernel extensions.

```c
// Uses pqrs::karabiner::driverkit::virtual_hid_device
```

--------------------------------

### Debug Memory Allocations

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Build the project with memory allocation debugging enabled and run with verbose logging to track memory usage in real-time.

```bash
zig build alloc -- -V
```

--------------------------------

### Define and Use Application Toggling Command

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/command-definitions.md

Define a command to toggle applications or open them if not running. Use quoted arguments for application names.

```shell
# Define app toggle command
.define toggle_app : yabai -m window --toggle {{1}} || open -a "{{1}}"
```

```shell
# Use for different applications
ralt - m : @toggle_app("YT Music")
ralt - n : @toggle_app("Notes")
ralt - t : @toggle_app("Microsoft Teams")
```

--------------------------------

### Code Signing for macOS

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Build the project with code signing enabled. This is an optional step, typically skipped in CI, but required for persistent accessibility permissions on macOS 15+.

```bash
zig build sign
```

--------------------------------

### Load External Configuration Files in skhd.zig

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Includes configurations from another skhd.zig file, allowing for modular configuration management.

```bash
.load "~/.config/skhd/extra.skhdrc"
```

--------------------------------

### Observe Key Events

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Use `skhd -o` to observe and echo every keycode and modifier that the tap detects. This is helpful for understanding how key presses are registered.

```bash
skhd -o
```

--------------------------------

### Linux-style Text Navigation and Deletion

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Configure shortcuts for word navigation and deletion, mimicking Linux behavior. This is useful for applications that do not natively support these shortcuts.

```bash
# Linux-style word navigation and deletion
ctrl - backspace [
    @native_apps ~         # Terminal apps handle natively
    *            | alt - backspace  # Other apps: delete word
]

ctrl - left [
    @native_apps ~         # Terminal apps handle natively
    *            | alt - left       # Other apps: move word left
]

ctrl - right [
    @native_apps ~         # Terminal apps handle natively
    *            | alt - right      # Other apps: move word right
]

# Home/End key behavior (with shift for selection)
home [
    @native_apps ~         # Terminal apps handle natively
    *            | cmd - left       # Other apps: line start
]

shift - home [
    @native_apps ~         # Terminal apps handle natively
    *            | cmd + shift - left  # Other apps: select to line start
]

# Ctrl+Home/End for document navigation
ctrl - home [
    @native_apps ~         # Terminal apps handle natively
    *            | cmd - up         # Other apps: document start
]

ctrl - end [
    @native_apps ~         # Terminal apps handle natively
    *            | cmd - down       # Other apps: document end
]
```

--------------------------------

### Distinguish Process Groups from Commands

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/command-definitions.md

Demonstrates the syntax difference between defining process groups (using array syntax) and command definitions (using colon syntax) to ensure backward compatibility.

```shell
# Process Groups: .define name ["app1", "app2"]
# Commands: .define name : command text
```

--------------------------------

### Inspect DriverKit Dext State

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Use `systemextensionsctl list` to inspect the activation and enabled state of DriverKit extensions, which may include the skhd or Karabiner-Elements dext.

```bash
systemextensionsctl list
```

--------------------------------

### Window Management with Custom Commands

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Utilize skhd.zig's custom command feature for window management operations like focusing, swapping, resizing, and switching spaces. This approach abstracts yabai commands into reusable functions.

```bash
# Focus windows using command definitions (New in skhd.zig!)
cmd - h : @yabai_focus("west")
cmd - j : @yabai_focus("south")
cmd - k : @yabai_focus("north")
cmd - l : @yabai_focus("east")

# Move/swap windows using command definitions
cmd + shift - h : @yabai_swap("west")
cmd + shift - j : @yabai_swap("south")
cmd + shift - k : @yabai_swap("north")
cmd + shift - l : @yabai_swap("east")

# Resize windows using command definitions
cmd + ctrl - h : @resize_window("left", "-20", "0")
cmd + ctrl - l : @resize_window("right", "20", "0")

# Switch spaces
cmd - 1 : yabai -m space --focus 1
cmd - 2 : yabai -m space --focus 2
```

--------------------------------

### SKHD Configuration Grammar Overview

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Formal grammar rules for skhd configuration syntax. Defines hotkeys, modes, actions, keysyms, modifiers, keys, literals, keycodes, process mappings, strings, group names, commands, and mode activations.

```plaintext
hotkey       = <mode> '<' <action> | <action>

mode         = 'name of mode' | <mode> ',' <mode>

action       = <keysym> '[' <proc_map_lst> ']'   | <keysym> '->' '[' <proc_map_lst> ']'
               <keysym> ':' <command>            | <keysym> '->' ':' <command>
               <keysym> ';' <mode_activation>    | <keysym> '->' ';' <mode_activation>
               <keysym> '~'

keysym       = <mod> '-' <key> | <key>

mod          = 'modifier keyword' | <mod> '+' <mod>

key          = <literal> | <keycode>

literal      = 'single letter or built-in keyword'

keycode      = 'apple keyboard kVK_<Key> values (0x3C)'

proc_map_lst = * <proc_map>

proc_map     = <string> ':' <command>         | <string> '~'   |
               '*'      ':' <command>         | '*'      '~'   |
               <string> ';' <mode_activation> |
               '*'      ';' <mode_activation> |
               '@' <group_name> ':' <command> |
               '@' <group_name> '~'           |
               '@' <group_name> ';' <mode_activation>

string       = '"' 'sequence of characters' '"'

group_name   = 'process group name defined with .define directive'

command      = <shell_command> | <command_reference>

shell_command = command is executed through '$SHELL -c' and
                follows valid shell syntax. if the $SHELL environment
                variable is not set, it will default to '/bin/bash'.
                when bash is used, the ';' delimiter can be specified
                to chain commands.

                to allow a command to extend into multiple lines,
                prepend '\' at the end of the previous line.

                an EOL character signifies the end of the bind.

command_reference = '@' <identifier> |
                    '@' <identifier> '(' <arg_list> ')'

arg_list     = <string> | <string> ',' <arg_list>

mode_activation = <mode> | <mode> ':' <command>

->           = keypress is not consumed by skhd

*            = matches every application not specified in <proc_map_lst>

~            = application is unbound and keypress is forwarded per usual
```

--------------------------------

### skhd.zig Configuration Directives Syntax

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Defines the general syntax for skhd.zig configuration directives, including .shell, .blacklist, .load, .path, .define, .device, .remap, and tap-hold attributes.

```plaintext
directive = '.shell' <string> |
            '.blacklist' '[' <string_list> ']' |
            '.load' <string> |
            '.path' <string> | '.path' '[' <string_list> ']' |
            '.define' <identifier> '[' <string_list> ']' |
            '.define' <identifier> ':' <command_template> |
            '.device' <identifier> '{' <device_attrs> '}' |
            '.remap' <hid_key> <device_clause> ':' <hid_key> |
            '.remap' <hid_key> <device_clause> '{' <taphold_attrs> '}'

device_attrs    = 'vendor:' <hex>  ',' 'product:' <hex>
device_clause   = '[' 'device' <identifier> ']'
taphold_attrs   = ( <taphold_attr> )+
taphold_attr    = 'tap'                ':' <hid_key>
                | 'hold'               ':' <hid_key_or_layer>
                | 'timeout'            ':' <duration>
                | 'permissive_hold'    ':' ('on' | 'off')
                | 'hold_on_other_key_press' ':' ('on' | 'off')
                | 'retro_tap'          ':' ('on' | 'off')
hid_key_or_layer = <hid_key> | <mode_identifier>   // mode = layer hold
duration         = <integer> ('ms' | 's')

string_list = <string> | <string> ',' <string_list>
```

--------------------------------

### Run skhd Locally with Logging

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Runs skhd locally for development and testing. It redirects verbose output to a log file for debugging. Note that a bare binary cannot be granted Accessibility/Input Monitoring permissions on macOS.

```bash
# Run skhd locally (signed dev .app — bare binary can't be granted
# Accessibility / Input Monitoring on Tahoe)
zig build run -- -V 2>&1 | tee /tmp/skhd.log
```

--------------------------------

### Define Simple and Placeholder Commands in skhd.zig

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Define simple commands or commands with placeholders for dynamic arguments. Placeholders are denoted by {{n}} and can be used in command definitions and when invoking them.

```bash
# Simple command without placeholders
.define focus_recent : yabai -m window --focus recent

# Command with placeholders
.define yabai_focus : yabai -m window --focus {{1}} || yabai -m display --focus {{1}}
.define window_action : yabai -m window --{{1}} {{2}}

# Use with @ prefix and arguments
cmd - tab : @focus_recent
cmd - h : @yabai_focus("west")
cmd + shift - h : @window_action("swap", "west")
```

--------------------------------

### Process-Specific Mode Activation with App Groups

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

Activates different modes based on the application in focus, using defined application groups. This allows for tailored shortcuts for sets of similar applications.

```bash
# Define terminal and browser app groups
.define terminal_apps ["kitty", "wezterm", "terminal"]
.define browser_apps ["chrome", "safari", "firefox"]

# Different apps switch to different modes with Cmd+M
cmd - m [
    @terminal_apps ; vim_mode : echo "Vim mode for terminals"
    @browser_apps ; browser_mode : echo "Browser mode activated"
    * ; default : echo "Back to default"
]
```

--------------------------------

### Define Template Command with Placeholders

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/command-definitions.md

Define command templates using {{n}} syntax for positional placeholders. Arguments must be enclosed in double quotes when calling the command.

```shell
.define yabai_focus : yabai -m window --focus {{1}} || yabai -m display --focus {{1}}
```

```shell
.define window_action : yabai -m window --{{1}} {{2}} || yabai -m display --{{1}} {{2}}
```

```shell
lcmd - h : @yabai_focus("west")
```

```shell
lcmd - j : @yabai_focus("south")
```

```shell
cmd + shift - h : @window_action("swap", "west")
```

```shell
cmd + shift - j : @window_action("swap", "south")
```

--------------------------------

### skhd.zig Passthrough Mode

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Explains and demonstrates passthrough mode in skhd.zig, where a command is executed while still allowing the keypress to be sent to the application.

```bash
# Execute command but still send keypress to application
cmd - p -> : echo "This runs but Cmd+P still goes to app"
```

--------------------------------

### Uninstall Grabber Script Logic

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/PLAN_GRABBER.md

This outlines the steps involved in uninstalling the skhd grabber, including unloading the launch daemon, and removing the associated files.

```bash
skhd --uninstall-grabber:
1. `launchctl bootout system /Library/LaunchDaemons/...`.
2. Remove plist and binary.
3. (User may also want to uninstall pqrs.org dext separately.)
```

--------------------------------

### Define and Use Reusable Yabai Commands

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/command-definitions.md

Define and utilize reusable yabai commands for window management, including focus, moving, and space switching. Ensure the number of arguments matches the highest placeholder number.

```shell
# Define reusable yabai commands
.define yabai_focus : yabai -m window --focus {{1}} || yabai -m display --focus {{1}}
.define yabai_move : yabai -m window --swap {{1}} || ( yabai -m window --display {{1}} ; yabai -m display --focus {{1}} )
.define yabai_space : yabai -m window --space {{1}}
```

```shell
# Use in hotkeys
lcmd - h : @yabai_focus("west")
lcmd - l : @yabai_focus("east")
cmd + shift - h : @yabai_move("west")
cmd + shift - 1 : @yabai_space("1")
cmd + shift - 2 : @yabai_space("2")
```

--------------------------------

### Symlink Application Bundle

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/CODE_SIGNING.md

Create a symbolic link for the skhd.app bundle in the /Applications directory. This is recommended for macOS Tahoe's System Settings picker.

```bash
ln -sfn "$(pwd)/zig-out/skhd.app" /Applications/skhd.app
```

--------------------------------

### Check skhd Status

Source: https://github.com/jackielii/skhd.zig/blob/main/README.md

Run these commands to quickly check the status of skhd components. `--status` provides a one-line summary, while `--grabber-status` offers a deeper dive into the grabber's dependencies.

```bash
skhd --status
```

```bash
skhd --grabber-status
```

--------------------------------

### Profile Event Handling

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Profile the event handling mechanism. This requires a Debug or ReleaseSafe build and should be run after building the project.

```bash
zig build && ./zig-out/bin/skhd -P
```

--------------------------------

### Upgrade and Verify skhd.zig on macOS Tahoe

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/UPGRADING.md

Use this command to upgrade skhd.zig via Homebrew and then re-register the service. Verify the status to ensure it's enabled and running.

```bash
brew upgrade skhd-zig

# Re-register via SMAppService. The `skhd` shim brew puts on PATH is a
# symlink into the bundle's inner binary, so SMAppService still sees the
# correct calling bundle and BTM gets a clean managed entry:
skhd --install-service

# Verify
skhd --status
# Expect: Registration status: enabled
#         Daemon running: Yes (PID …)
#         Hotkeys functional: Yes (event tap active)
```

--------------------------------

### Define Simple Command

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/command-definitions.md

Define a command without any parameters. Use the '@' symbol to reference the defined command in a hotkey.

```shell
.define focus_recent : yabai -m window --focus recent || yabai -m space --focus recent
```

```shell
cmd - tab : @focus_recent
```

--------------------------------

### Proposed skhd.zig Dual-Function Key Syntax

Source: https://github.com/jackielii/skhd.zig/blob/main/docs/PLAN_ADVANCED_FEATURES.md

Proposed configuration syntax for skhd.zig to implement dual-function keys (to_if_alone). It supports separate definitions for tap and hold actions.

```shell
# Caps Lock → Escape (tap) / Control (hold)
caps_lock : ctrl
caps_lock [alone] : escape

# Alternative syntax
caps_lock -> ctrl | escape
```

--------------------------------

### Basic Hotkey Binding

Source: https://github.com/jackielii/skhd.zig/blob/main/SYNTAX.md

A simple hotkey binding that executes a command when a specific key combination is pressed. This is the most basic form of hotkey configuration.

```bash
cmd - a : echo "Command+A pressed"
```

--------------------------------

### Mode Activation with Command

Source: https://github.com/jackielii/skhd.zig/blob/main/CLAUDE.md

Activates a mode and executes a command simultaneously. This can be used in global hotkeys, process lists, or process groups.

```skhdrc
key ; mode : command
```