DOCSEARCHbyAlgolia
Submit Docs

skhd Documentation

repository·master·Indexed 27 days ago

https://github.com/asmvik/skhd

A high-performance, responsive hotkey daemon for macOS. skhd allows users to define custom keyboard shortcuts via a simple DSL, supporting modal hotkeys, application-specific bindings, and live configuration reloading. It includes a CLI for managing the daemon as a launchd service and a flexible configuration system using skhdrc files.

Tokens
987
Snippets
3
Records
5
Agent score
43%

What's inside skhd

  1. Install skhd via Homebrew or Source

    master

    Homebrew

    Requires xcode-8 command-line tools.

    brew install asmvik/formulae/skhd
skhd --start-service

    Source

    Requires xcode-8 command-line tools.

    git clone https://github.com/asmvik/skhd
make install      # release version
make              # debug version

    Important Setup Notes:

    • On first run, you must grant access to the Accessibility API in macOS settings and then restart skhd.
    • Secure Keyboard Entry must be disabled in your applications for skhd to receive key events.
    brew install asmvik/formulae/skhd
skhd --start-service

  2. Configure skhd hotkeys and modes

    master

    Hotkeys are defined in a text file using a simple DSL. skhd supports hotloading, meaning you can edit the config and reload it live using skhd -r.

    Configuration File Locations

    skhd looks for configuration in this order:

    1. $XDG_CONFIG_HOME/skhd/skhdrc
    2. $HOME/.config/skhd/skhdrc
    3. $HOME/.skhdrc

    You can override this with skhd -c <path>.

    Hotkey Syntax

    A hotkey consists of a keysym and an action.

    • keysym: <mod>-<key> (e.g., shift-alt-7 or cmd-a).
    • action:
      • <keysym> : <command>: Execute a command.
      • <keysym> -> <command>: Execute a command and do not consume the keypress (passthrough).
      • <keysym> [ <proc_map_lst> ]: Execute command only for specific processes.
      • <keysym> ; <mode>: Switch to a new mode.

    Mode Syntax

    Modes allow for modal hotkey systems (e.g., a 'navigation' mode).

    • ::name @ : <command>: Declare a mode that captures keypresses regardless of bindings.
    • ::name : <command>: Declare a mode with an entry command.
    • ::name: Declare a mode.

    Command Execution

    Commands are executed via $SHELL -c (defaults to /bin/bash if $SHELL is unset). Use \ at the end of a line to allow multi-line commands.

  3. Use .load and .blacklist in skhd configuration

    master

    You can use special directives in your skhdrc to manage configuration modularity and application filtering.

    Include additional config files

    Use .load to include other files. If the path starts with /, it is treated as an absolute path; otherwise, it is relative to the current config file.

    .load "/Users/user/.config/partial_skhdrc"
.load "partial_skhdrc"

    Blacklist applications

    Use .blacklist to prevent skhd from monitoring events for specific processes.

    .blacklist [
    "terminal"
    "qutebrowser"
    "kitty"
    "google chrome"
]
    .load "/Users/Koe/.config/partial_skhdrc"
.load "partial_skhdrc"

.blacklist [
    "terminal"
    "qutebrowser"
    "kitty"
    "google chrome"
]

  4. Manage skhd as a launchd service

    master

    Use the following commands to manage the skhd lifecycle via macOS launchd:

    • skhd --install-service: Install the launchd service file to ~/Library/LaunchAgents/com.asmvik.skhd.plist.
    • skhd --uninstall-service: Remove the launchd service file.
    • skhd --start-service: Run skhd as a service through launchd.
    • skhd --restart-service: Restart the skhd service.
    • skhd --stop-service: Stop the skhd service.
    skhd --install-service
skhd --uninstall-service
skhd --start-service
skhd --restart-service
skhd --stop-service

  5. Use skhd CLI flags

    master

    Commonly used command-line arguments for skhd:

    FlagDescription
    -c, --config <path>Specify location of config file
    -r, --reloadSignal a running instance to reload its config file
    -o, --observeOutput keycode and modifiers of event (Ctrl+C to quit)
    -k, --key <keysym>Synthesize a keypress (uses same syntax as config)
    -t, --text <text>Synthesize a line of text
    -V, --verboseOutput debug information
    -P, --profileOutput profiling information
    -v, --versionPrint version number to stdout
    -h, --no-hotloadDisable system for hotloading config file