Workspaces

Sweets provides numbered workspaces from 1 through 10. Their count and multi-monitor model are configured in sweets.general. Optional sweets.workspace rules give individual workspace numbers a preferred monitor.

General workspace settings

sweets.general({
  workspace_mode = "shared",
  workspace_count = 10,
  workspace_move_follow = false,
})

See General configuration for the complete behavior of these settings.

Pinning a workspace

sweets.workspace(number, { ... }) assigns a preferred monitor to one workspace number.

sweets.workspace(1, { monitor = "eDP-1" })
sweets.workspace(4, { monitor = "DP-1" })

Find connector names with:

sweets msg outputs

Connector matching is exact and case-sensitive. The monitor name must not be empty. Each workspace number can be declared once per configuration layer. A user declaration for the same number replaces the installed declaration.

You may pin several workspace numbers to the same monitor. Only one can be visible there at a time. Switching between them replaces the visible workspace on that monitor.

Pins in shared mode

In "shared" mode, each number identifies one workspace across the whole session. A pinned workspace returns to its preferred monitor whenever that monitor is connected.

• Switching to the workspace selects its pinned monitor.
• Moving a window there also sends it to that monitor.
• The workspace can be visible on only one monitor at a time.

Unpinned workspaces use their current or remembered monitor. A hidden empty workspace opens on the selected monitor.

Pins in per-monitor mode

In "per_monitor" mode, every monitor normally has its own copy of each workspace number. A pin makes one monitor the owner of that number.

• Switching to the number selects the owning monitor's copy.
• Moving a window to the number sends it to the owning copy.
• Existing same-number contents from other monitors move into the owning copy.

Disconnected monitors

A missing or disabled monitor does not make a pinned workspace unreachable. Sweets keeps the pin and places the workspace on an active monitor when needed.

When the preferred monitor reconnects, the workspace returns to it. Windows and focus are preserved where possible.

Workspace count

workspace_count enables a consecutive range starting at workspace 1. Setting it to 5 enables workspaces 1 through 5.

sweets.general({
  workspace_count = 5,
})

A pin above the active count remains valid but has no effect until that number is enabled. Bindings, IPC requests, and desktop components cannot activate a workspace above the active count.

Lowering the count moves windows from disabled workspaces to the last enabled workspace in the same scope. No windows are discarded.

Switching workspaces

Use the workspace binding action with a number:

for number = 1, 9 do
  sweets.bind("MOD+" .. number, "workspace", number)
end

sweets.bind("MOD+0", "workspace", 10)

The standard installed configuration already provides these bindings. A workspace that is visible on another monitor selects that monitor instead of creating another shared copy.

You can also switch through IPC:

sweets msg workspace 4

Moving windows between workspaces

Use workspace_move to move the focused window:

for number = 1, 9 do
  sweets.bind("MOD+Shift+" .. number, "workspace_move", number)
end

sweets.bind("MOD+Shift+0", "workspace_move", 10)

The standard installed configuration also provides these bindings.

workspace_move_follow controls what happens next:

• false: keep the source workspace selected.
• true: select the destination and retain focus on the moved window.

The equivalent IPC command is:

sweets msg move-to-workspace 4

Moving a floating window between monitors translates its remembered geometry into the destination monitor's coordinate space.

Inspecting workspaces

Show every enabled numbered workspace, its monitor, and whether it is active:

sweets msg workspaces

Use JSON output for scripts:

sweets msg --json workspaces

In per_monitor mode, the list can contain the same public number more than once. The output field identifies which monitor owns each copy.

Panels and other workspace-protocol clients receive the same enabled numbered workspace set. Numbers above workspace_count are not published.

Opening applications on a workspace

Use a window rule to place future matching applications on a workspace:

sweets.window_rule({
  app_id = "org.mozilla.firefox",
  workspace = 2,
})

See Window rules for matching, monitor selection, and opening behavior.

Special workspace

The special workspace is separate from numbered workspaces. It cannot use a sweets.workspace rule and is not included in sweets msg workspaces.

sweets.bind("MOD+S", "special_toggle")
sweets.bind("MOD+Shift+S", "special_move")

Inspect it separately with:

sweets msg special-workspace

See Layout configuration for its dimmer and workspace behavior.

Reload behavior

A valid reload applies pin changes immediately. Sweets keeps the selected workspace and focused window when possible. A new ownership conflict can move a workspace and its windows to the newly pinned monitor.

Removing a pin stops enforcing that monitor home. It does not need to move an already visible workspace immediately.

Validate and reload the configuration with:

sweets --check-config
sweets msg reload

An invalid rule rejects the complete candidate. Sweets keeps the last valid workspace configuration active.