Quick start
This is a minimal configuration to start tiling. You can add more options later
as you explore. Replace ~/.hammerspoon/init.lua with:
hs.loadSpoon("Shoji")spoon.Shoji:start()Reload Hammerspoon from the menu bar (Reload config) or run this in the Hammerspoon console:
hs.reload()Windows in the current macOS Space arrange in the default tall layout:
┌─────────────────────────────┬─────────────────────────────┐│ │ ││ │ ││ │ ││ │ 2 ││ │ ││ │ ││ │ ││ 1 ├─────────────────────────────┤│ │ ││ │ ││ │ ││ │ 3 ││ │ ││ │ ││ │ ││ │ ││ │ │└─────────────────────────────┴─────────────────────────────┘What happens
Once Shoji starts:
- Windows in the current macOS Space arrange in the tall layout
- New windows join the layout automatically
- Closing a window causes remaining windows to fill the gap
- Each macOS Space maintains its own layout and window order
Try the keybindings
Default hotkeys use Ctrl+Alt as the modifier.
Focus:
- Focus left: Ctrl+Alt+H
- Focus down: Ctrl+Alt+J
- Focus up: Ctrl+Alt+K
- Focus right: Ctrl+Alt+L
- Focus next: Ctrl+Alt+N
- Focus previous: Ctrl+Alt+P
Swap:
- Swap left: Ctrl+Alt+Shift+H
- Swap down: Ctrl+Alt+Shift+J
- Swap up: Ctrl+Alt+Shift+K
- Swap right: Ctrl+Alt+Shift+L
- Swap next: Ctrl+Alt+Shift+N
- Swap previous: Ctrl+Alt+Shift+P
- Swap with main: Ctrl+Alt+Return
Layout and state:
- Cycle layout: Ctrl+Alt+Space
- Toggle floating: Ctrl+Alt+Shift+T
See keybindings for the full list.
Exclude apps from tiling
Some apps work better floating. Add them to the blocklist:
hs.loadSpoon("Shoji")
spoon.Shoji:configure({ filter_mode = "blocklist", filter_apps = { "com.apple.finder", "com.apple.systempreferences", },})
spoon.Shoji:start()Find an app’s bundle ID with:
osascript -e 'id of app "Safari"'