SKHD - Simple Hotkey Daemon

SKHD provides global hotkeys for seamless application launching and window management integration with Yabai.

🎯 Overview

SKHD (Simple Hotkey Daemon) is a lightweight hotkey daemon for macOS that enables global keyboard shortcuts. It’s tightly integrated with Yabai for window management and provides quick access to frequently used applications.

Key Features

Global Hotkeys: System-wide keyboard shortcuts
Application Launching: Quick access to development tools
Window Management: Integration with Yabai tiling
Modifier Keys: Uses meh (ctrl+alt+shift) and hyper (ctrl+alt+cmd+shift)

🚀 Application Shortcuts

All application shortcuts use the meh key (ctrl+alt+shift) for consistency and to avoid conflicts.

Space map

17 spaces. Display 1 holds 1-8, display 2 holds 9-17.

Space	Display	App
1	1	Ghostty
2	1	LibreOffice
3	1	Dia (stack)
4	1	Chrome, Devin
5	1	Cursor
6	1	Preview, Foxit
7	1	Alter
8	1	Obsidian
9	2	Slack
10	2	Telegram
11	2	Zalo
12	2	Discord, WhatsApp (stack)
13	2	Arc
14	2	Cliq
15	2	kitty
16	2	ChatGPT, Claude, Codex, Grok (stack)
17	2	ego lite

Development Tools

Shortcut	Application	Description
`meh + a`	Ghostty	Focus the primary terminal and move the pointer to it
`meh + f`	Kitty	Secondary terminal emulator on display 2, space 15
`meh + x`	ChatGPT	AI assistant on display 2, space 16
`meh + g`	Cursor	AI-powered code editor on space 5
`meh + y`	Alter	Chat hub on space 7

Browsers & Communication

Shortcut	Application	Description
`meh + s`	Dia	Primary web browser on space 3
`meh + e`	Ego	Lightweight browser on display 2, space 17
`meh + d`	Arc	Browser on space 13
`meh + z`	Zen Browser	Alternative browser
`meh + k`	Slack	Team communication on space 9
`meh + r`	Telegram	Messaging app on space 10
`meh + u`	Zalo	Messaging app on space 11
`meh + t`	Discord	Community chat on space 12
`meh + h`	WhatsApp	Messaging app on space 12
`meh + j`	Cliq	Team communication on space 14

Productivity & AI Tools

Shortcut	Application	Description
`meh + v`	Grok Bot	Grok desktop app on space 16
`meh + c`	Claude	AI assistant on display 2, space 16
`meh + l`	Perplexity	AI search engine
`meh + i`	Structured	Task and time management
`meh + w`	LibreOffice	Office suite on space 2
`meh + p`	Foxit PDF Reader	PDF reader on space 6
`meh + o`	Preview	macOS preview app on space 6
`meh + n`	Obsidian	Notes on space 8
`meh + m`	superwhisper	Voice input
`meh + q`	Apple Music	Music player
`meh + b`	Borumi	Productivity app

🪟 Window Management

SKHD integrates with Yabai for powerful window management capabilities.

Window Focus

Shortcut	Action	Description
`ctrl + shift + h`	Focus West	Move focus to left window
`ctrl + shift + j`	Focus South	Move focus to bottom window
`ctrl + shift + k`	Focus North	Move focus to top window
`ctrl + shift + l`	Focus East	Move focus to right window
`ctrl + shift + tab`	Focus Stack	Toggle the visible window in a stacked space

Window Movement

Shortcut	Action	Description
`cmd + shift + h`	Warp West	Move window to the left
`cmd + shift + l`	Warp East	Move window to the right

Window Resizing

Shortcut	Action	Description
`hyper + left`	Resize Left	Decrease width from left
`hyper + down`	Resize Down	Increase height downward
`hyper + up`	Resize Up	Decrease height upward
`hyper + right`	Resize Right	Increase width to right

Space Management

Shortcut	Action	Description
`hyper + 1-9`	Send to Space	Move window to specific space
`hyper + tab`	Send to Recent	Move window to recent space
`cmd + ctrl + 1-4`	Move & Follow	Move window and follow to space
`cmd + ctrl + ←/→`	Move to Display	Move window to previous/next display and follow

Layout Controls

Shortcut	Action	Description
`hyper + e`	Balance Windows	Equalize window sizes
`hyper + f`	Toggle Fullscreen	Zoom fullscreen
`shift + alt + f`	Native Fullscreen	macOS native fullscreen
`shift + alt + space`	Toggle Float	Float/unfloat window
`alt + r`	Rotate Clockwise	Rotate layout 270°
`shift + alt + r`	Rotate Counter	Rotate layout 90°

Gap Controls

Shortcut	Action	Description
`hyper + i`	Toggle Gaps	Enable/disable gaps and padding
`hyper + o`	Toggle Padding	Toggle padding only

⚙️ Configuration

Configuration File

Location: dotfiles/skhd/.config/skhd/skhdrc
Reload: skhd --restart-service

Key Modifier Definitions

# Modifier key definitions
meh = ctrl + alt + shift          # Primary modifier for apps
hyper = ctrl + alt + cmd + shift  # Secondary modifier for window management

Adding New Shortcuts

Application Shortcuts

# Template for new application
meh - [key] : open "/Applications/AppName.app"

# Example: Add new app
meh - q : open "/Applications/Notion.app"

Window Management Shortcuts

# Template for window actions
[modifier] - [key] : yabai -m window --[action] [parameters]

# Example: New resize shortcut
hyper - 0 : yabai -m space --balance

Service Management

# Start SKHD service
brew services start skhd

# Stop SKHD service
brew services stop skhd

# Restart SKHD service
brew services restart skhd
skhd --restart-service

# Check service status
brew services list | grep skhd

🔧 Troubleshooting

Common Issues

Shortcuts Not Working

# Check if SKHD is running
ps aux | grep skhd

# Restart SKHD service
skhd --restart-service

# Check for configuration errors
skhd --verbose

Permission Issues

# SKHD needs accessibility permissions
# Go to: System Preferences → Security & Privacy → Privacy → Accessibility

Application Not Opening

# Verify application path
ls "/Applications/AppName.app"

# Check if application exists
mdfind "kMDItemDisplayName == 'AppName'"

# Test opening manually
open "/Applications/AppName.app"

Conflicts with Other Apps

# Check for conflicting shortcuts
# Some apps may override global shortcuts

# Use different modifier combinations
# Consider using hyper instead of meh for some shortcuts

Configuration Debugging

Test Configuration

# Check configuration syntax
skhd --config-file ~/.config/skhd/skhdrc --verbose

# Monitor key events
skhd --observe

# Reload configuration
skhd --reload

Key Code Discovery

# Find key codes for special keys
skhd --observe
# Press the key you want to map
# Note the key code displayed

Performance Optimization

Reduce Latency

# Minimize delay in shortcuts
# Avoid complex shell commands in shortcuts
# Use direct application paths instead of scripts when possible

Memory Usage

# Monitor SKHD memory usage
ps aux | grep skhd

# SKHD should use minimal memory
# If high usage, check for configuration loops

📚 Advanced Configuration

Conditional Shortcuts

# Different shortcuts based on active application
# Example: Different behavior in terminal vs browser

Mode-Based Shortcuts

# Create different modes for different workflows
# Example: Development mode vs presentation mode

Integration with Scripts

# Call custom scripts from shortcuts
meh - p : ~/.local/bin/project-setup.sh

# Pass parameters to scripts
meh - shift - p : ~/.local/bin/project-setup.sh --template react

Dynamic Application Detection

# Open different apps based on context
# Example: Open appropriate terminal based on current project

🔗 Integration

Yabai Integration

Window management shortcuts directly control Yabai
Seamless tiling and space management
Consistent modifier keys across both tools

Tmux Integration

Application shortcuts work from within tmux sessions
Terminal applications respect tmux session context

Neovim Integration

Shortcuts work while Neovim is focused
No conflicts with Neovim’s key mappings