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()

Note

Loading the spoon makes it available, but tiling only begins when you call :start(). You can call :configure() between loading and starting to customize behavior.

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.

Cheatsheet

Press Ctrl+Alt+Shift+/ at any time to show an overlay with all available keybindings. Press Esc to dismiss it.

Press Ctrl+Alt+/ to open the command palette and switch layouts or run actions.

Focus:

• Focus left: Ctrl+Alt+H
• Focus right: Ctrl+Alt+L
• Focus up: Ctrl+Alt+K
• Focus down: Ctrl+Alt+J
• Focus next: Ctrl+Alt+N
• Focus previous: Ctrl+Alt+P

Swap:

• Swap left: Ctrl+Alt+Shift+H
• Swap right: Ctrl+Alt+Shift+L
• Swap up: Ctrl+Alt+Shift+K
• Swap down: Ctrl+Alt+Shift+J
• Swap next: Ctrl+Alt+Shift+N
• Swap previous: Ctrl+Alt+Shift+P
• Swap main: Ctrl+Alt+Shift+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"'

Having trouble?

If windows aren’t tiling or keybindings don’t respond, check the Troubleshooting page.

Next steps

• Customize keybindings
• Configure gaps and layouts
• Learn about layouts
• Compose custom layouts — combine modifiers and combinators to create layouts like mirrored tall, gapped BSP, or adaptive layouts that switch based on window count

Using Vim? The default keybindings already use HJKL for navigation. See the Vim workflow recipe for tips on integrating Shoji into a Vim-centric setup.

Multiple monitors? Shoji tiles each screen independently. See the multi-monitor recipe for per-screen layouts and focus across displays.

Want to build custom layouts? Follow the building layouts tutorial to create a layout from scratch, add configuration, and compose layouts with modifiers and combinators.