KiwiDesk Documentation

KiwiDesk is a tiling window manager for macOS. Windows live in a flat list per space, layouts are pure functions over that list, and everything is configurable twice over: visually in the Settings app, or in Lua (~/.config/KiwiDesk/init.lua).

Where to go

• User Guide — what the Settings app cannot tell you: how settings interact, where things live, which profile loads.
• Spaces & Desktops — how your screens, macOS’s Desktops, profiles and KiwiDesk’s Spaces fit together.
• Lua Reference — the complete init.lua API, every setting in expects → does → example form.
• CLI & IPC — every command, the event stream, and the raw socket protocol.
• Recipes — ready-to-copy integrations: SketchyBar, JankyBorders, and more.

For contributors

• Design Decisions — the why behind settled product and UX behavior.
• Settings UI Patterns — the shared control conventions every Settings surface follows.
• Translating — the localization workflow and how to add a language.

Install

Requirements: macOS 14 or later on Apple silicon.

brew install --cask kiwicanopy/tap/kiwidesk

Or download the signed, notarized .dmg from kiwidesk.kiwicanopy.com and drag KiwiDesk into your Applications folder. It is the same app; the cask additionally puts the kiwidesk CLI on your PATH, which the CLI page shows how to link after a .dmg install. Either way KiwiDesk checks for updates itself.

The User Guide covers the starter setup, Start at login, and the Accessibility permission under Troubleshooting. If windows stop being managed after an upgrade, re-approve KiwiDesk in System Settings › Privacy & Security › Accessibility.

To build it yourself, swift build -c release produces .build/release/KiwiDesk, which takes the same commands.