A modular Hammerspoon configuration using a custom hyperkey (Caps Lock → F19) for application launching, window management, and custom keybindings.

• Hyperkey Modal: Caps Lock mapped to F19 acts as a hyperkey with tap/hold detection
  • Tap: Opens Spotlight (⌘Space)
  • Hold + Key: Triggers custom keybindings
• Application Launcher: Quick launch/focus apps with single keystrokes
• Window Management: Vim-style window focus navigation and Rectangle Pro integration
• Special Functions: Config reload, screenshots, voice mode toggle

• Hammerspoon installed
• Karabiner-Elements for remapping Caps Lock → F19
  • Open Karabiner-Elements
  • Go to Simple Modifications → For all devices
  • Map: caps_lock → F19

~/.hammerspoon/
├── init.lua                    # Main entry point, loads all modules
├── hyperkey.lua                # Core hyperkey modal logic and helper functions
├── keybinds_apps.lua           # Application launch/focus keybindings
├── keybind_finder.lua          # Custom Finder window handler
├── keybinds_window_mgmt.lua    # Window management and focus keybindings
└── keybinds_special.lua        # Special function keybindings

Focus Navigation (Hyper + hjkl)

• Hyper+H - Focus window to the left
• Hyper+J - Focus window below
• Hyper+K - Focus window above
• Hyper+L - Focus window to the right

Rectangle Pro Integration (Hyper+Shift+Key)

These keybindings forward to Rectangle Pro using Ctrl+Alt+Cmd+Shift+Key:

• Hyper+Shift+] - Window to right half
• Hyper+Shift+[ - Window to left half
• Hyper+Shift+H/J/K - Window positioning (first fourth, center half, last fourth)
• Hyper+Shift+Y/U/I - Window positioning (top left, top half, top right)
• Hyper+Shift+N/M/, - Window positioning (bottom left, bottom half, bottom right)
• Hyper+Shift+Space - Maximize

• Hyper+Shift+R - Reload Hammerspoon config
• F13 - Screenshot to clipboard (⌘⇧4)
• F14 - Toggle Caps Lock (for Claude voice mode)

When a window is closed, the next visible window is automatically focused (with a 0.1s delay to ensure window list updates).

Edit hyperkey.lua:

local SPOTLIGHT_DELAY = 0.15  -- Adjust tap detection threshold (seconds)

Edit keybinds_window_mgmt.lua:

local WINDOW_FOCUS_DELAY = 0.1  -- Delay after window close (seconds)

The hyperkey system uses Hammerspoon's modal hotkey functionality:

1. Pressing F19 enters the modal immediately (for instant response to key combos)
2. A timer tracks whether the key was held or tapped
3. On release:
   • Quick tap: Triggers Spotlight and exits modal
   • Held: Just exits modal (key combo already executed)

bindApp(mods, key, app)

• Binds Hyper+mods+key to launch or focus an application

bindSpecial(mods, key, targetMods, targetKey)

• Binds Hyper+mods+key to send a different keystroke
• Useful for forwarding to apps that don't recognize F19

Edit keybinds_apps.lua:

bindApp({}, 'X', "Your App Name")
bindApp({'shift'}, 'X', "Another App")

Edit keybinds_window_mgmt.lua:

f19:bind({}, "key", function()
  -- Your custom window management code
end)

Current version: 1.0

MIT