Recipes

Real-world integration patterns for KiwiDesk. All recipes use either Lua event callbacks or the CLI event stream — no plugins required.

Integration approaches

Lua hooks (in init.lua): Subscribe to events within the KiwiDesk Lua VM and trigger side effects directly. This is the fastest path: no subprocess overhead, stateless, fire-and-forget. Use this for tools that accept external command invocation (sketchybar --trigger, borders active_color=...).

CLI event stream (shell scripts, other processes): Use kiwidesk subscribe <events...> to receive newline-delimited JSON from a separate terminal session or script. Query state on-demand with kiwidesk get_state and kiwidesk list_monitors. Use this when you need durable polling, cross-process communication, or your tool runs in a different sandbox (like Hammerspoon).

External commands (KiwiDesk.exec)

Commands run asynchronously in the background and never block window management. They append /opt/homebrew/bin and /usr/local/bin to the child’s PATH so Homebrew tools resolve. See the Lua reference for the full KiwiDesk.exec and os.execute API, including callback, timeout, and output capture.

Binary path note: installed through the Homebrew cask, KiwiDesk is on your PATH as plain kiwidesk — use that directly. If you built from source instead, it is not on PATH: use the absolute path to your built binary (e.g., ~/path/to/KiwiDesk/.build/release/KiwiDesk) or symlink it yourself. The recipes below keep the path in a variable like KIWIDESK=kiwidesk so either setup works.

Recipe pages

• SketchyBar — spaces widget with click to focus, window icons, layout-aware styling. The flagship integration.
• JankyBorders — layout-aware border colors via the layout_change event.
• Miscellaneous — shell scripts, event stream queries, Hammerspoon, per-desktop keybinds.