KiwiDesk

https://kiwidesk.kiwicanopy.com/docs
Admin
KiwiDesk is a tiling window manager for macOS that provides configurable layouts, multi-monitor...
Tokens:327,737
Snippets:1,981
Trust Score:4.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Startup script example with KiwiDesk.set_gap_global, KiwiDesk.exec, and KiwiDesk.on

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Commands at init.lua top level run on load and reload. This example sets base gaps before profiles load, fires an async command, and subscribes to the space_change event.

```lua
-- Set base gaps; these apply before a profile loads.
KiwiDesk.set_gap_global(10)


-- Fire an async command at startup:
KiwiDesk.exec("sketchybar --reload")


-- Subscribe to an event:
KiwiDesk.on("space_change", function(space_id)
    print("Switched to space: " .. space_id)
end)
```

--------------------------------

### stack.promote example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window to the master zone. Expects nothing.

```lua
stack.promote()
```

--------------------------------

### Install KiwiDesk via Homebrew

Source: https://kiwidesk.kiwicanopy.com/docs

Use this command to install the KiwiDesk application and add the kiwidesk CLI to your PATH.

```bash
brew install --cask kiwicanopy/tap/kiwidesk
```

--------------------------------

### KiwiDesk CLI usage examples

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Shows the basic command forms for the kiwidesk binary: running the window manager, sending commands, and querying help or version. The Homebrew cask installs it as lower-case kiwidesk on PATH; a source build produces .build/release/KiwiDesk instead.

```bash
kiwidesk                      # run the window manager
kiwidesk <command> [args...]  # send a command to the app
kiwidesk help                 # local usage
kiwidesk --version            # local version (no app needed)
kiwidesk list_commands        # every command, grouped
kiwidesk help <name>          # one command's arguments
```

--------------------------------

### Define float_rules in Lua

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Example of a float_rules table configuration. This matches all windows of the Calculator app and specifically the 'Get Info' window of the Finder app.

```lua
float_rules = {
    "com.apple.calculator",
    "com.apple.finder:Get Info",
}
```

--------------------------------

### Example Profile JSON Configuration

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

A sample profile JSON file demonstrating monitor sets, layout strategies, window settings, and custom keybindings.

```json
{
  "name": "Desk One",
  "default": true,            // this count's fallback profile
  "monitor_sets": [
    {
      "monitors": ["Built-in Retina Display:1728x1117"],
      "space_monitor_map": {  // explicit pins only (sparse)
        "2": "Built-in Retina Display:1728x1117"
      }
    }
  ],
  "main_spaces": ["1"],       // follow the main display
  "fallback_space": "1",      // rehome target on switch
  "saved_at": "2026-07-04T12:00:00Z",
  "settings": {
    "drag": {
      "corner_radius": 16,
      "ghost": {
        "enabled": true, "border": true,
        "border_color": "#347957", "border_width": 5,
        "border_alignment": "inside",
        "fill": true, "fill_color": "#34795740"
      },
      "drop_zone": {
        "enabled": true, "border": true,
        "border_color": "#C2790A", "border_width": 5,
        "border_alignment": "inside",
        "fill": true, "fill_color": "#C2790A40"
      }
    },
    "gap": {
      "global": {
        "inner": { "horizontal": 20, "vertical": 20 },
        "outer": {
          "top": 20, "bottom": 20, "left": 20, "right": 20
        }
      },
      "override": {}              // per space id
    },
    "layout": {
      "bsp": {
        "new_window_placement": "after_focused",
        "ratio_h": 0.5,
        "ratio_v": 0.5,
        "strategy": "alternating"
      },
      "grid": { "columns": 3, "rows": 2, "type": "dynamic",
                "fill_empty_cells": true,
                "split_direction": "horizontal",
                "new_window_placement": "last" },
      "monocle": { "orientation": "horizontal",
                   "app_bar": { "enabled": true,
                                "edge": "top",
                                "background_style": "boxed",
                                "item_size": 0 } },
      "scroll": { "anchor": "follow", "slot_size": 0,
                  "new_window_placement": "after_focused" },
      "stack": { "master_count": 1, "master_ratio": 0.6,
                 "overflow_style": "cascade_overflow",
                 "new_window_placement": "first" }
    },
    "min_window_size": 300,
    "new_window_placement_override": {},  // per space id
    "space": { "icon": { "2": "envelope" } }  // per space id
  },
  "space_modes": { "1": "stack", "2": "bsp" },
  // Optional sparse keybinding override (see Config
  // cascade): only the layers/rows this profile changes.
  // Omit the key entirely to inherit the base shortcuts.
  "layers": [
    {
      "name": "default",
      "bindings": [
        { "combo": "alt+h", "lua": "KiwiDesk.focus(\"left\")",
          "kind": "custom", "label": "" }
      ]
    }
  ]
}
```

--------------------------------

### app_bar.set_alignment example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Places the item group along the bar while it fits. Expects 'start', 'center', or 'end' (default 'center'). Values are edge-relative; once items overflow and scroll, all three values behave the same.

```lua
app_bar.set_alignment("start")
```

--------------------------------

### stack.set_stack_position example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets which side of the space the stack zone takes. Expects "top", "right" (default), "bottom", or "left". The master zone gets the rest; left/right split the width, top/bottom the height. The stack zone's lineup derives from the position.

```lua
stack.set_stack_position("bottom")
```

--------------------------------

### KiwiDesk.spawn_new(bundleIdentifier)

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Always launches a new instance of the app, even if one is already running. Matching is keyed on the bundle id.

```APIDOC
## KiwiDesk.spawn_new(bundleIdentifier)

### Description
Always launches a new instance of the app, even if one is already running. Matching is keyed on the bundle id.

### Method
Function call

### Parameters
- **bundleIdentifier** (string) - Required - The app bundle identifier (e.g., com.apple.Terminal).

### Example
```lua
KiwiDesk.bind("ctrl+alt+return", function()
    KiwiDesk.spawn_new("com.apple.Terminal")
end)
```
```

--------------------------------

### Event hooks example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Example of using event hooks that coexist with the GUI-managed settings.

```lua
-- Event hooks, control flow, helpers, print, locals — all fine.
for _, event in ipairs({ "space_change", "focus_change" }) do
  KiwiDesk.on(event, function()
    KiwiDesk.exec("sketchybar --trigger kiwidesk_update")
  end)
end
```

--------------------------------

### Build KiwiDesk from source

Source: https://kiwidesk.kiwicanopy.com/docs

Use this command to build the KiwiDesk binary from source. The resulting executable is located at .build/release/KiwiDesk.

```bash
swift build -c release
```

--------------------------------

### move_space_to_display example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves a whole space to a monitor immediately and shows it there. The display reference can be a 1-based number (1 is main) or a monitor fingerprint/name. This is a runtime move; use pin_space_to_display to make it persist across dock/undock. Creates the space if it does not exist.

```lua
KiwiDesk.move_space_to_display("mail", 2)      -- second monitor
KiwiDesk.move_space_to_display(3, "DELL U2723QE:3840x2160")

```

--------------------------------

### Install borders via Homebrew

Source: https://kiwidesk.kiwicanopy.com/docs/recipes/jankyborders

Install the borders tool, which JankyBorders relies on, using Homebrew on macOS. Run this command in your terminal to set up the borders utility.

```bash
brew install felixkratz/formulae
```

--------------------------------

### Command Listing Output Format

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Example of the command listing format, showing command groups and their respective arguments.

```text
scroll
  set_anchor <anchor>                Sets where the focused …
  set_orientation <orientation>      Sets whether columns scroll …
  set_slot_size_override <space> <size>   Overrides the slot …
```

--------------------------------

### KiwiDesk.exec

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Starts a shell command in the background and returns immediately. Accepts a command string, optional callback, timeout, and dedup flag. Returns the child's pid or nil if the command could not be started or was skipped as a duplicate.

```APIDOC
## KiwiDesk.exec

### Description
Starts a shell command in the background and returns immediately. The command is run via /bin/sh -c, so pipes, quoting, &&, and $PATH lookups work as in a terminal. Returns the child's pid (a number), or nil when the command could not be started or was skipped as a duplicate.

### Method
N/A (Lua function)

### Parameters
- **command** (string) - Required - The command string to run via /bin/sh -c.
- **callback** (function) - Optional - Called once the command has exited, with arguments: code (number, exit code), stdout (string, everything written to stdout), stderr (string, everything written to stderr).
- **timeout** (number) - Optional - Number of seconds before the command receives SIGTERM. Defaults to 30 s. Pass 0 or negative for no limit.
- **dedup** (boolean) - Optional - Default true. If an identical command is already running, a second exec is skipped (returns nil) and its callback is not invoked. Pass false to allow parallel identical commands.

### Return Value
- **pid** (number) - The child's process ID, or nil if the command could not be started or was skipped as a duplicate.

### Notes
- stdout and stderr are each capped at ~1 MB; output beyond the cap is truncated and ends with '[output truncated at 1 MB]'.
- Exec children are fire-and-forget; when KiwiDesk exits, running children are re-parented to launchd and finish naturally.
- When the number of outstanding children crosses 20, KiwiDesk logs a warning. The live count is available via get_state().exec_running.
- The child's PATH gets /opt/homebrew/bin and /usr/local/bin appended.

### Example
```lua
-- Fire and forget:
KiwiDesk.exec("sketchybar --reload")

-- Read a command's output via the callback:
KiwiDesk.exec("defaults read -g AppleInterfaceStyle",
    function(code, out, err)
        dark = (code == 0 and out:match("Dark") ~= nil)
    end)

-- With a 5-second timeout:
KiwiDesk.exec("some-slow-tool", function(code, out, err)
    -- code is non-zero if killed by the watchdog
end, 5)

-- No limit (deliberately long-running), and opt out of dedup so
-- two identical copies can run at once:
KiwiDesk.exec("long-running-tool", nil, 0, false)
```
```

--------------------------------

### KiwiDesk.exec usage examples

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Demonstrates fire-and-forget execution, reading command output via callbacks, setting custom timeouts, and disabling deduplication for long-running processes.

```lua
-- Fire and forget:
KiwiDesk.exec("sketchybar --reload")


-- Read a command's output via the callback:
KiwiDesk.exec("defaults read -g AppleInterfaceStyle",
    function(code, out, err)
        dark = (code == 0 and out:match("Dark") ~= nil)
    end)


-- With a 5-second timeout:
KiwiDesk.exec("some-slow-tool", function(code, out, err)
    -- code is non-zero if killed by the watchdog
end, 5)


-- No limit (deliberately long-running), and opt out of dedup so
-- two identical copies can run at once:
KiwiDesk.exec("long-running-tool", nil, 0, false)
```

--------------------------------

### Example window lifecycle event payloads

Source: https://kiwidesk.kiwicanopy.com/docs/cli

Sample JSON event payloads for window creation and destruction events.

```json
{"event": "window_created",
 "data": {"window_id": 4711, "app": "Ghostty",
          "space_id": "2", "reason": "new",
          "bundle_id": "com.mitchellh.ghostty"}}
{"event": "window_destroyed",
 "data": {"window_id": 4711, "app": "Ghostty",
          "space_id": "2", "reason": "closed",
          "bundle_id": "com.mitchellh.ghostty",
          "desktop": null}}
```

--------------------------------

### Set Space Bar alignment

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Places Space items and the front-app segment along the bar. Accepts "start", "center", or "end", default "center". Values are edge-relative; for a left bar, start is its top.

```lua
space_bar.set_alignment("center")
```

--------------------------------

### KiwiDesk.move_to_space_and_follow(space)

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Moves the focused window to the specified space and switches you there with it.

```APIDOC
## KiwiDesk.move_to_space_and_follow(space)

### Description
Moves the focused window to the specified space and switches you there with it.

### Method
Function call

### Endpoint
KiwiDesk.move_to_space_and_follow(space)

### Parameters
- **space** (number or string) - Required - A space identifier.

### Request Example
```lua
KiwiDesk.move_to_space_and_follow("mail")
KiwiDesk.move_to_space_and_follow(3)
```

### Response
No return value documented.
```

--------------------------------

### app_bar.set_highlight_color example

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Sets the highlight color of the active indicator (outline or edge mark).

```lua
app_bar.set_highlight_color("#8DB354")
```

--------------------------------

### os.execute usage examples

Source: https://kiwidesk.kiwicanopy.com/docs/lua-reference

Shows the fire-and-forget nature of os.execute and warns against assuming synchronous completion for file system operations.

```lua
-- Fine: fire-and-forget side effect.
os.execute("open -a Spotify")


-- Wrong: the file is NOT guaranteed to exist yet here.
os.execute("touch /tmp/marker")
-- do_something("/tmp/marker")
```
Tokens:
Raw