Concepts

This page explains the terminology used throughout Shoji’s documentation. If you’re new to tiling window managers, start here.

Spaces

A space is a macOS virtual desktop. Each space has its own layout and window order. Shoji tracks state per-space, so switching spaces restores the layout you were using there.

You can create new spaces in Mission Control (Ctrl+↑) or by swiping up with three fingers on the trackpad.

Multi-monitor support

Each monitor has its own set of spaces, and Shoji manages them independently. This means:

• Each screen can use a different layout simultaneously
• Window order is tracked per-space, not per-screen
• Switching spaces on one monitor doesn’t affect others
• Layout state (ratio, main count) is preserved per-space

When you focus a window, Shoji operates on the space containing that window. Actions like “cycle layout” or “increase main ratio” affect only the current space on the current screen.

Tiling vs floating

Tiled windows are managed by Shoji. They snap to a grid defined by the current layout and resize automatically when other windows are added or removed.

Floating windows are exempt from tiling. They can overlap other windows and be positioned freely. Toggle a window’s floating state with Ctrl+Alt+Shift+T.

Zoomed windows are temporarily floated and maximized to fill the screen. Press Ctrl+Alt+F to zoom, and press again to restore the window to its tiled position.

Some apps float by default (dialogs, preferences windows). You can also configure entire apps to always float using filter_apps.

Layouts

A layout defines how tiled windows are arranged. Shoji includes several built-in layouts:

Layout	Description
Tall	Main window on left, others stacked on right
Wide	Main window on top, others stacked below
BSP	Binary space partitioning (recursive halving)
Grid	Equal-sized windows in rows and columns
Column	Equal-width side-by-side columns
Three columns	Main center, stacks on sides
Monocle	All windows stacked at full size
Floating	No automatic tiling

Press Ctrl+Alt+Space to cycle through enabled layouts.

Main area

In main-stack layouts (Tall, Wide, Three columns), the screen is split into two regions:

• Main area: The larger region, typically for your primary focus window
• Stack: The smaller region where secondary windows are arranged

Two settings control the main area:

• main_ratio (0.1–0.9): How much screen space the main area occupies
• main_count: How many windows appear in the main area

For example, with main_ratio = 0.6 and main_count = 1, one window takes 60% of the screen and the rest share the remaining 40%.

Window order

Shoji maintains a window order for each space. This order determines which windows go where in the layout:

• Window 1 goes to the first slot (usually main area)
• Window 2 goes to the second slot
• And so on…

You can reorder windows by:

• Swapping with directional keys (Ctrl+Alt+Shift+H/J/K/L)
• Swapping with main (Ctrl+Alt+Shift+Return)

New windows are inserted after the currently focused window.

Focus

Focus determines which window receives keyboard input. The focused window typically has a highlighted title bar.

Shoji provides focus navigation:

Keys	Action
Ctrl+Alt+H/J/K/L	Focus by direction
Ctrl+Alt+N/P	Focus next/previous in order

Actions

An action is something Shoji can do: focus a window, swap positions, change layouts, etc. Actions are triggered by keybindings or IPC commands.

See the Actions reference for the complete list.

Hooks

A hook is a callback function that runs when something happens (window created, layout changed, etc.). Use hooks to integrate Shoji with other tools or customize behavior.

See Hooks for details.

State persistence

Shoji saves your window manager state to disk so it survives Hammerspoon restarts and config reloads. The state file lives at ~/.local/state/shoji/state.json (or $XDG_STATE_HOME/shoji/ if you’ve set that variable).

For each space, Shoji persists:

• Layout — which layout is active
• Main ratio and main count — your sizing adjustments
• Window order — the order windows appear in the layout
• Layout-specific state — BSP tree structure, Partition regions, and similar internal data

Floating window state is also preserved per-window, so windows you’ve toggled to floating stay floating after a reload.

The persistence schema is versioned. When you upgrade Shoji, the core fields (layout, ratio, counts) are always restored, but layout-specific state may reset if its format changed between versions. Extensions can persist their own state through the same mechanism.