Configuration Guide

Paneru is configured via a TOML file or a Lua script — never both. By default, it looks for the TOML configuration in the following locations (in order):

1. $PANERU_CONFIG (environment variable)
2. $HOME/.paneru
3. $HOME/.paneru.toml
4. $XDG_CONFIG_HOME/paneru/paneru.toml

The configuration is automatically reloaded when the file is saved.

If an init.lua exists (see Lua Scripting Guide), it takes over completely and none of these TOML paths are read.

1. Global Options ([options])

General behavior settings for the window manager.

2. Padding ([padding])

Sets the margins at the edges of the screen.

3. Swipe & Gestures ([swipe])

Configure trackpad gestures and scroll-wheel window sliding.

[swipe.gesture]

When fingers_count is omitted or set below 3, Paneru does not intercept native macOS gestures. If macOS uses three-finger horizontal swipes for Spaces, prefer [swipe.scroll] with a modifier or configure a different finger count.

Paging estimates physical distance from the trackpad's reported device size. The centimeter threshold may feel slightly different across devices; adjust page_distance_cm to suit your trackpad. Haptics require compatible hardware and may be suppressed by macOS when fingers are no longer touching it.

To move one window at a time with the existing focus animation:

Each additional 2 cm of horizontal finger travel selects another window. Haptics are on by default in paging mode; set haptics = false to disable the pulses while keeping the same paging behavior.

[swipe.scroll]

To select windows with Alt + mouse wheel, enable window steps:

Window steps use the current focus commands and scroll direction. Repeated inputs in the same direction are limited to one step every 180 milliseconds. Momentum is ignored. Trackpad gestures and vertical workspace scrolling keep their existing behavior.

4. Decorations ([decorations])

Visual styling for workspaces, active and inactive windows.

Virtual Workspace indicators

Toggles display of the currently active virtual workspace in the menubar or in a brief status popup window. Both are enabled by default. workspace_menu_status controls only the workspace indicator; the descriptor and menu remain available.

Example:

[decorations.menu]

Basic settings for the menubar display.

To hide Paneru from the menu bar:

Or in init.lua:

You can also click Hide Menu Bar in Paneru's menu. This choice is saved across restarts and overrides enabled. To show the item again:

This command shows the item in the running daemon and remembers the new choice. Lua scripts can use paneru.showmenu() and paneru.hidemenu(), or bind showmenu and hidemenu to keys. Choices are stored in $XDG_STATE_HOME/paneru/menu-bar.json (normally ~/.local/state/paneru/menu-bar.json); removing this file while Paneru is stopped restores the configuration's behavior.

The permission setup menu remains visible until the required macOS access is granted.

[decorations.menu.descriptor]

Settings for the descriptor component of the menubar display. The descriptor component is a visual marker for the Paneru menubar item.

[decorations.menu.indicator]

Settings for the indicator component of the menubar display. The indicator component shows your current (and optionally all active) virtual workspace(s).

Important Note: The 'unicode' and 'marked' formats only mean anything next to the workspaces they are not, so they are incompatible with the single-item 'mono' and 'paged' styles and will fall back to 'default'.

[decorations.inactive.dim] (Native macOS Dimming)

Paneru supports native macOS window dimming. To use this mode, only set opacity (and optionally opacity_night). Do not set a color.

Example:

5. Keybindings ([bindings])

Bindings map a key combination to an action. A binding can be a single string or an array of strings.

Format: "[modifiers-]key". For example alt + cmd - j and cmd - j.

Available modifiers are:

• alt, lalt, ralt
• ctrl, lctrl, rctrl
• cmd, lcmd, rcmd
• shift, lshift, rshift
• fn

For a full list of parseable keys (i.e. leftarrow) check the source: https://github.com/karinushka/paneru/blob/3790b01f8d65df5d9000142db7cf25f9270dcccc/src/config.rs#L1466-L1601

Window commands

Example:

Virtual workspaces (Experimental)

Paneru allows having virtual spaces inside of the native macOS workspace. Logically it can be thought of several strips of windows (rows) stacked on top of each other within the single workspace. Similar to how Niri implements the movement between the vertical workspaces.

Shifting up or down goes to the previous or next strip of windows - wrapping around at the start or the end.

Moving the last window out of the virtual row, will "collapse it".

Virtual workspaces can also be navigated using trackpad gestures. If [swipe.gesture] is configured, a vertical 3/4-finger swipe will switch between virtual workspace rows, while horizontal swipes continue to scroll the strip as usual. For mouse users, see the vertical_modifier option under [swipe.scroll].

Example:

Example command line:

See QUERY_AND_SUBSCRIBE_FORMAT.md for the structured paneru query responses and paneru subscribe event stream.

6. Window Rules ([windows])

Define specific behaviors for applications based on their Title, Bundle ID, or accessibility role/subrole.

For example, use width = "complement_focused" in a window rule to give each new window the width remaining beside the currently focused window. A new window opened from a full-width window also starts at full width. This width is chosen during initial placement, before the window_spawned Lua hook runs.

Example:

Windows whose subrole isn't AXStandardWindow or AXFloatingWindow (e.g. AXDialog) are ignored by Paneru unless a rule with manage = true matches them, so a role/subrole rule for such windows only takes effect for apps that are also force-managed.

Example:

Copying a window rule

Neither the bundle ID nor the exact window title is visible anywhere in the UI, so the Paneru menu bar has a Copy Window Rule entry. You can also trigger it via a keybinding (e.g., window_copyrule = "ctrl + alt - c") or run it from the command line (paneru window copyrule). It puts a rule for the currently focused window on the clipboard, ready to paste:

The two matchers are live; everything else is a comment for you to uncomment. title is anchored and regex-escaped so it matches only this window — swap in the commented .* to cover every window of the app instead. The app, role and subrole line is there to tell one pasted rule from the next. role and subrole are also offered as commented-out matchers above it (omitted when the window doesn't report one); uncomment them to target, say, only an app's dialogs (with manage = true, see above). When an init.lua is in charge, the snippet is written as a Lua table instead of TOML.

Forcing management of LSUIElement or non-standard windows

Some applications (e.g., BetterTouchTool, ProtonVPN) are flagged as background apps (LSUIElement) or expose windows with unusual accessibility roles such as AXTable or AXTextField. Paneru normally ignores these processes and windows. Use manage = true to opt in and forcibly manage the matching windows.

Session Restore

Paneru saves its managed window layout and can restore it the next time it starts. Restore is a startup-only phase: Paneru loads the saved session, applies it after initial window discovery, keeps matching open for a short grace period, then stops consulting the saved state until the next Paneru process start.

The saved session includes:

• native workspace ids
• virtual workspace rows and the selected row per native workspace
• layout structure: singles, stacks, tabs, and fullscreen strips
• display/screen association
• window identity for matching across restarts

Matched startup windows use the saved session before static [windows] rules. That means saved layout, virtual workspace, display, and managed/floating state win over configured index, floating, width, and grid rules during restore. Unmatched startup windows, and all windows created after the restore grace period ends, keep normal [windows] behavior.

Example:

Restore matches windows first by stable startup identity:

• window id
• process id
• bundle id

If an application has restarted and those ids changed, Paneru can use a conservative fallback match:

• bundle id
• non-empty window title
• window identifier
• accessibility role
• accessibility subrole

Fallback matching is only used when it is unambiguous. If multiple current windows could match the same saved window, Paneru skips that saved window rather than moving the wrong one.

If a saved app or window is missing, the default "ignore" policy simply drops it from the restored layout. Empty stacks, tab groups, columns, and virtual rows are removed. If the previously selected virtual row is removed because all of its windows are missing, Paneru selects the nearest remaining restored row for that native workspace. If no restored row remains, the normal startup workspace selection is kept.

For screens, Paneru prefers the current macOS workspace-to-display mapping when the workspace is already present on a display. Otherwise it restores to the saved display id when that screen is still connected, then falls back to the current active display, then the first available display by id. Paneru does not create placeholder displays or off-screen state for disconnected monitors.

7. Experimental Features

Inactive Window Overlay Dimming

Another dimming option that draws a translucent overlay on every inactive window to visually emphasize the focused one.

Activation: This mode is enabled by setting both opacity and color under [decorations.inactive.dim]. In this mode, opacity ranges from 0.0 to 1.0.

Example:

Active Window Border

Draws a colored border around the currently focused window.

Example:

In Dark Mode, the border uses color_night. If color_night is not set, the border uses color, then the legacy border_color option, then white. In Light Mode, the border ignores color_night. The border changes color immediately when the macOS appearance changes.

Tip: You can override the border_radius for specific applications in the [windows] section. See Window Rules.

8. Lua Scripting

Paneru embeds a Lua runtime that allows full configuration via init.lua, replacing paneru.toml entirely. When a Lua configuration or script exists ($PANERU_LUA, $HOME/.paneru.lua, or $XDG_CONFIG_HOME/paneru/init.lua), it takes over completely and no TOML config is read.

All options, padding, gesture settings, window rules, and keybindings documented in sections 1–7 above are available under identical names via paneru.setup{...}.

In addition to static configuration, Lua scripting allows:

• Event Hooks (paneru.on): React to window creation (window_spawned), focus changes, or space switches with optional filter specs or regex matchers.
• Keybinding Callbacks (paneru.bind): Map hotkeys to custom Lua callbacks or commands.
• State Queries (paneru.query_*): Read real-time window, workspace, and display layout state without round-trip shell executions.
• Persistent State (paneru.state): Store and mutate data across reloads and daemon restarts.
• Programmatic Layout Transformations (ws): Pure layout operations (ws:focus, ws:swap, ws:float, ws:shift, ws:view, etc.) for custom workflows like named scratchpads.

For complete documentation, event specifications, API reference, and examples, see the Lua Scripting Guide.