Shoji — tiling for macOS

The idea

On Linux, a tiling compositor like Hyprland places every window for you: no dragging, no overlapping, no hunting for the one underneath. The keyboard moves focus, swaps windows and switches workspaces, and the whole layout is one plain config file.

Shoji brings that way of working to macOS, for the apps you already use. It doesn't replace the Mac's desktop or ask you to turn off System Integrity Protection. It arranges ordinary windows through the Accessibility API, keeps them clear of the menu bar and the Dock, and gets out of the way when you quit — every window comes back on screen.

What it does

Dwindle tiling

New windows split the focused tile, alternating sides, with inner and outer gaps. Drag a border to resize; drop a tile on another to swap them.

Workspaces in the menu bar

Ten virtual workspaces, shown as numbered pills next to the clock. Switching is instant — no macOS Spaces animation, no private APIs.

Keyboard first

Hyprland's bindings on ⌥ (or ⌃⌥, or ⌘): focus, move, resize, float, fullscreen, pin and send windows to workspaces. ⌥-drag moves any window.

A config file you can read

shoji.conf is hyprland.conf-style — binds, window rules, floating workspaces, startup programs. It reloads on save and shows errors in a banner.

Themes

The Lucent theme set — Catppuccin, Tokyo Night, Gruvbox, Nord, Rosé Pine and more. A theme also sets kitty's colours, the wallpaper, Dark or Light mode and the accent colour.

Machines and Containers

Two companion apps: Linux VMs from cloud images on Apple's Virtualization framework (⌥M), and Docker containers and images (⌥O).

Keys

Mod is ⌥ Option by default. ⌥/ shows every binding.

⌥ ↩	Terminal (kitty)
⌥ ⇧ D	App launcher
⌥ ← → ↑ ↓	Move focus
⌥ ⇧ ← → ↑ ↓	Swap windows
⌥ ⌃ ← → ↑ ↓	Resize
⌥ 1 … 0	Go to workspace
⌥ ⇧ 1 … 0	Send window to workspace
⌥ F · ⌥ ⌃ V · ⌥ J	Fullscreen · float · flip the split
⌥ Q	Close window
⌥ M · ⌥ O · ⌥ I	Machines · Containers · Stats
⌥ ,	Settings

shoji.conf

Everything you'd expect from hyprland.conf, in ~/.config/shoji/shoji.conf. The first start writes a commented file listing every key, dispatcher and rule.

# your own bindings ($mod follows the modifier in Settings)
bind = $mod, T, exec, open -na kitty --args htop
bind = $mod SHIFT, B, exec, open -na "Google Chrome"

# window rules
windowrule = float, app:Calculator
windowrule = workspace 3 silent, app:Mail
windowrule = size 1100 700, app:kitty, title:^htop

# a floating workspace, and programs to start once per login
workspace = 9, floating
exec-once = open -ga Docker

Install

Open the disk image and double-click the installer. It puts Shoji, Shoji Machines and Shoji Containers in /Applications.
If macOS refuses to open it, that's because the installer isn't notarized yet: go to System Settings → Privacy & Security and click Open Anyway, or Control-click the installer and choose Open.
Open Shoji and allow it under Accessibility (System Settings → Privacy & Security → Accessibility). It starts by itself once allowed, and its workspace numbers appear in the menu bar.
Install kitty, the terminal Shoji opens with ⌥↩: brew install --cask kitty, or from sw.kovidgoyal.net/kitty. Containers also needs Docker.

Use a single macOS Space — Shoji's workspaces take their place. Only the main display is managed for now. To quit, press ⌥⇧M or use the menu-bar menu; every window comes back on screen.

Get it

One disk image with the installer for all three apps. Apple silicon, macOS 13 Ventura or later. No developer tools needed.

Download for Mac

2026-11-14 · 7f1f1d6Apple siliconmacOS 13+2.6 MB

sha256 checksum