Why tiling?
Tiling window managers automatically arrange windows into non-overlapping regions. Instead of manually dragging and resizing, you press a key and windows snap into place.
When tiling helps
Section titled “When tiling helps”Tiling works best when you:
- Switch between multiple windows frequently (code + terminal + browser)
- Want consistent window positions without manual arrangement
- Prefer keyboard over mouse for window management
- Work on large or multiple monitors where manual positioning is tedious
- Need to see multiple windows at once (comparing files, watching logs)
When tiling doesn’t help
Section titled “When tiling doesn’t help”Tiling may not suit your workflow if you:
- Work primarily in one full-screen app
- Prefer floating windows that overlap
- Use apps with many small utility windows (design tools, DAWs)
- Need pixel-perfect manual positioning
You can always disable tiling for specific apps or toggle individual windows to floating.
Comparing alternatives
Section titled “Comparing alternatives”| Feature | Shoji | yabai | Amethyst | AeroSpace | Rectangle Pro |
|---|---|---|---|---|---|
| SIP changes required | No | Yes* | No | No | No |
| Composable layouts | Yes | No | No | No | No |
| Per-space layout | Yes | Yes | Yes | Yes | No |
| Layout modifiers | Yes | No | No | No | No |
| Custom layouts | Lua scripting | Scripting | Limited | TOML config | None |
| Focus follows mouse | No | Yes | Yes | Yes | No |
| Window gaps | Yes | Yes | Yes | Yes | Yes |
| Dependencies | Hammerspoon | None | None | None | None |
* yabai runs without SIP changes but loses scripting additions (focus follows mouse, window opacity, etc.)
yabai is the most powerful option but requires disabling System Integrity Protection for full features. Best for users comfortable with system modifications.
Amethyst is simple and works out of the box. Good for users who want basic tiling without configuration. Limited customization options.
AeroSpace is newer, config-file driven, and focuses on keyboard workflows. Supports tree-based layouts similar to i3.
Rectangle Pro is a commercial app focused on manual window snapping with some tiling features. Less automation, more direct control.
Shoji emphasizes composability — combine layouts, wrap them with modifiers, and build exactly what you need. Requires Hammerspoon but needs no system modifications.
Who Shoji is for
Section titled “Who Shoji is for”Shoji works well for users who:
- Already use or are willing to install Hammerspoon
- Want to customize window management beyond preset layouts
- Prefer Lua scripting over config files
- Need different layouts per macOS Space
- Want layout composition (mirror, center, partition)
Who Shoji isn’t for
Section titled “Who Shoji isn’t for”Consider alternatives if you:
- Want zero configuration (try Amethyst)
- Need focus-follows-mouse (try yabai or AeroSpace)
- Prefer tree-based layouts like i3 (try AeroSpace)
- Don’t want to write Lua for advanced customization
Next steps
Section titled “Next steps”Ready to try it? Continue to Installation.