Default keybindings

Shoji uses Ctrl+Alt as the primary modifier to avoid conflicts with macOS Option key special characters. Navigation follows Vim-style H/J/K/L for directional movement.

These keybindings are enabled automatically when you call spoon.Shoji:start(), so you can start using them right away.

Move focus between windows.

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
Focus previous (history): Ctrl+Alt+Tab

Window swapping

Swap window positions while maintaining focus on the same window.

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 control

Change how windows are arranged on screen.

Cycle layout: Ctrl+Alt+Space
Increase main ratio: Ctrl+Alt+=
Decrease main ratio: Ctrl+Alt+-
Increase nmaster: Ctrl+Alt+,
Decrease nmaster: Ctrl+Alt+.
Retile space: Ctrl+Alt+Shift+R

Main ratio controls how much screen space the main area occupies (Tall and Wide layouts). nmaster controls how many windows appear in the main area (Tall and Wide layouts).

Window state

Toggle floating: Ctrl+Alt+Shift+T

Floating windows stay outside the tiling layout and can be moved freely.

Help

Toggle cheatsheet: Ctrl+Alt+Shift+/

Displays an overlay showing all keybindings. Press Escape or the same shortcut to dismiss.

BSP layout actions

These bindings only apply when using the BSP (binary space partitioning) layout.

Shrink horizontal: Ctrl+Cmd+H
Expand horizontal: Ctrl+Cmd+L
Shrink vertical: Ctrl+Cmd+K
Expand vertical: Ctrl+Cmd+J
Rotate split: Ctrl+Cmd+R

Custom keybindings

Calling bindHotkeys() merges your bindings with defaults. Your bindings override defaults for the same action:

-- Only override specific bindings; others use defaults
spoon.Shoji:bindHotkeys({
  focus_left = { { "cmd", "alt" }, "h" },  -- Override
  focus_right = { { "cmd", "alt" }, "l" }, -- Override
  -- All other actions use default bindings
})

To disable a specific binding, set it to an empty table:

spoon.Shoji:bindHotkeys({
  focus_right = {},  -- Disabled (no keybinding)
})

Hotkey format

Shoji accepts two formats for specifying hotkeys:

-- Standard Spoon format (modifiers as nested table)
{ { "ctrl", "alt" }, "h" }

-- Flat format (modifiers and key in single table)
{ "ctrl", "alt", "h" }

Available modifiers: ctrl, alt, cmd, shift, fn.

Cheatsheet configuration

Customize the keybinding cheatsheet appearance:

spoon.Shoji:configure({
  cheatsheet_style = "system",      -- "light", "dark", or "system" (default)
  cheatsheet_opacity = 0.9,         -- Background opacity (0.1-1.0)
  cheatsheet_font = "Menlo",        -- Font for shortcut keys
  cheatsheet_show_unbound = false,  -- Hide actions without keybindings
})

The cheatsheet can be dismissed by pressing Escape or the same toggle shortcut (Ctrl+Alt+Shift+/).

On smaller screens or with many custom bindings, the cheatsheet may not display all keybindings. Set cheatsheet_show_unbound = false to reduce content, or use a larger display.