How tiling works

Shoji follows one rule: each new window takes half of the newest space. There are no grids to draw, so you always know where the next window will go. That’s the Grid layout, the default. Columns and tall screens work a little differently; see Grid, Columns and tall screens.

The fold

1 window            2 windows           3 windows           4 windows
┌───────────────┐   ┌───────┬───────┐   ┌───────┬───────┐   ┌───────┬───────┐
│               │   │       │       │   │       │   2   │   │   1   │   2   │
│       1       │   │   1   │   2   │   │   1   ├───────┤   ├───────┼───────┤
│               │   │       │       │   │       │   3   │   │   4   │   3   │
└───────────────┘   └───────┴───────┘   └───────┴───────┘   └───────┴───────┘

One window fills the screen: all the room below the menu bar and beside the Dock. It isn’t macOS full-screen mode, so the menu bar and Dock stay where they are.
Two windows share the screen side by side. Your first window stays on the left. It’s the primary window.
Three windows: the right half splits top and bottom, so every window stays in view.
Four windows make a 2×2 grid. The primary gives the bottom half of its column to the fourth window, so on a laptop every window keeps a usable size.

Grid, Columns and tall screens

Grid (the default) is the fold above: one big window, the rest folded beside it, and a 2×2 grid for four.
Columns puts every window side by side, full height, the primary on the left, sharing the width equally. Only as many columns tile as fit at a usable width: three on a MacBook, four on a bigger monitor.
A tall screen (a monitor turned on its side) always stacks its windows in rows, the primary on top, at most three, whichever layout you picked.

Pick the layout for every screen in Settings → Layout → Layout, or for one screen in the menu bar panel under Windows on this screen.

The order of windows

Windows are placed in the order you opened them (or, when Shoji starts, the order it finds them). The first window is the primary.

When you close a window, the rest keep their order and fill the space. Close the primary and the next window becomes primary. You can change the order any time by swapping windows.

How many windows each screen holds

Each screen tiles up to 3 windows by default. You can choose anything from 1 to 4:

For one screen: in the menu bar panel under Windows on this screen, or press ⌃⌥⌘ with 1 to 4.
As the default for every screen: Settings → Layout → Windows per screen.

The number you pick belongs to that screen in the macOS Space you’re on, and the screen keeps your last pick after Shoji restarts or the display is plugged in again.

When you open more windows than the screen holds, the new window joins the tile you’re working in, on top, at the same size; the window that was there waits behind it. Switch between them with ⌃⌥`, the grip, ⌘-Tab or the Dock. See Stacks.

If you’d rather keep one window per tile, set Settings → Layout → When a screen is full to Float in the middle: the extra window then moves to the middle of the screen once and stays wherever you put it, a short This Space is full notice appears at the bottom of the screen, and the window joins the layout when a tiled window closes.

Which windows are tiled

Shoji tiles ordinary app windows: the kind with a title bar and the three buttons. It leaves these where they are:

Dialogs, sheets, panels and pop-ups.
Minimized windows and windows in full-screen mode.
Windows that can’t be resized.
Apps you’ve chosen not to tile, and iPhone Mirroring (its fixed, phone-shaped window doesn’t fit a layout). See Floating and excluding windows.

Some apps refuse to get smaller than a certain size. Shoji learns that size and plans around it. See Apps that won’t shrink.

When windows move

Shoji rearranges the windows on a screen when a window opens, closes, is minimized or hidden, moves to another screen, or when you change a setting that affects the layout. It notices a click on a close or minimize button straight away, so the other windows start moving while the window is still animating away.