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).

Seven layouts ship out of the box — bsp, stack, scrolling (PaperWM-style), monocle, grid, track, and floating — with per-space overrides, profiles that follow your monitor setup, and integration with macOS Desktops. Every layout is fully reconfigurable: each carries its own optional parameters, so the shape it opens in is yours to set as the default, globally or per space.

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.
• Spaces & Desktops — how your screens, macOS’s Desktops, profiles and KiwiDesk’s own Spaces fit together. Read this if a Desktop switch ever landed you somewhere you did not expect.
• 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

Requirements: macOS 14 or later on Apple silicon. Install it with Homebrew:

brew install --cask kiwicanopy/tap/kiwidesk

That installs the app and puts the kiwidesk CLI on your PATH. The User Guide covers the starter setup, starting at login, and the Accessibility permission under Troubleshooting.

Or download the signed, notarized .dmg from kiwidesk.kiwicanopy.com and drag KiwiDesk into your Applications folder. It is the same app; what Homebrew adds is the kiwidesk CLI on your PATH, which the CLI page explains how to link after a .dmg install.

Later builds install themselves — KiwiDesk checks in the background and offers you the update. Upgrade an older copy through Homebrew once to reach a version that can do that; the User Guide covers the rest.

Releases are signed with a stable Developer ID and notarized. If windows stop being managed after an upgrade, re-approve KiwiDesk in System Settings › Privacy & Security › Accessibility.

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