KiwiDesk Documentation

KiwiDesk is a tiling window manager for macOS. Windows live in a flat list per virtual 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).

Six layouts ship out of the box — bsp, stack, scrolling (PaperWM-style), monocle, grid, and floating — with per-space overrides, profiles that follow your monitor setup, and native macOS Spaces integration.

Where to go

• User Guide — the Settings app: layouts, profiles, shortcuts, monitors, and the visual editor. Start here if you configure KiwiDesk through the app.
• Lua Reference — the complete init.lua API, every setting in expects → does → example form. Start here if you hand-write your config.
• CLI & IPC — every command, the event stream, and the raw socket protocol, for scripts and external tools.
• 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 (public beta)

KiwiDesk is in public beta and installs through Homebrew:

brew install --cask kiwicanopy/tap/kiwidesk

That installs the app and puts the kiwidesk CLI on your PATH; start the background service with kiwidesk service start. The User Guide covers the Accessibility permission and first-run setup.

Later builds arrive with brew upgrade --cask kiwidesk. Until KiwiDesk ships a signed .app, an upgrade changes the binary and macOS drops its Accessibility grant — re-approve it in System Settings › Privacy & Security › Accessibility if windows stop being managed.

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