Configuration
Tessera reads a YAML configuration file. This reference lists the recognized settings, their defaults and intended effects. A setting does not establish support for a platform or guarantee that the active backend can perform every operation. XFCE/X11 with Xfwm4 is the first-release target; its support-manifest evidence remains implemented-unverified, with same-commit CI and real-session smoke pending.
For layout descriptions see Built-in layouts; for user scripts see Custom layouts. The source checkout contains a commented example at crates/tessera-config/examples/tessera.yml. The schema is crates/tessera-config/src/schema/keys.rs; the generated source reference is docs/configuration.md. The generator writes that source reference, not this wiki page. Source paths in the tables are local checkout paths, not wiki links.
File location and reload
An absolute, nonempty XDG_CONFIG_HOME selects $XDG_CONFIG_HOME/tessera/tessera.yml. Otherwise Linux and macOS use ~/.config/tessera/tessera.yml, resolving home from HOME or, if unset, the account’s passwd entry. On Windows an existing %HOME%/.config/tessera/tessera.yml is the legacy candidate; otherwise the path is %APPDATA%/Tessera/tessera.yml. If both distinct Windows candidates exist, resolution reports a conflict; there is no automatic migration. Path rules are not a platform-support claim.
Unrecognized and platform-specific keys are preserved and diagnosed rather than silently discarded. Make a backup before hand-editing. For a controller running with the user service installed, reload with systemctl --user reload tessera; alternatively, send the daemon SIGHUP with pkill -HUP tessera on Linux. These commands apply only when that service or process is present.
For example:
layouts: [tall, wide, grid]
window-margins: true
window-margin-size: 8
mod1: [option, shift]
cycle-layout:
mod: mod1
key: spaceThe layouts cycle accepts built-in keys; custom scripts are selected separately. A binding is a mod/key mapping or false to disable it. The default mod1 is Alt+Shift and mod2 is Alt+Shift+Ctrl.
Contents
- Tiling settings
- Preferences
- Layout configuration
- Modifier groups
- Command bindings
- Screen shortcuts
- Workspace shortcuts
- Tiling activation shortcuts
Decoded Settings
Settings that directly determine tiling geometry, screen padding, margins, and window filtering rules.
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
window-max-count |
integer (0..=u32::MAX) | 0 |
Maximum number of windows to tile per workspace; 0 means unlimited. | crates/tessera-config/src/persistence.rs:28 |
tiling-enabled |
boolean | true |
Whether automatic window tiling management is active. | crates/tessera-config/src/persistence.rs:33 |
window-margins |
boolean | false |
Whether tiled windows maintain outer margin spacing between them. | crates/tessera-config/src/persistence.rs:36 |
smart-window-margins |
boolean | false |
Whether window margins only apply when more than one window is visible. | crates/tessera-config/src/persistence.rs:38 |
window-margin-size |
integer (0..=u32::MAX) | 0 |
Gap between tiled windows in pixels when window-margins is enabled. | crates/tessera-config/src/persistence.rs:41 |
window-minimum-width |
integer (0..=u32::MAX) | 0 |
Minimum width for tiled windows in pixels; 0 disables the limit. | crates/tessera-config/src/persistence.rs:47 |
window-minimum-height |
integer (0..=u32::MAX) | 0 |
Minimum height for tiled windows in pixels; 0 disables the limit. | crates/tessera-config/src/persistence.rs:53 |
floating |
list | [] |
Applications or window title patterns that float instead of tiling. | crates/tessera-config/src/persistence.rs:58 |
floating-is-blacklist |
boolean | true |
Whether the floating rules list acts as a blacklist (true) or whitelist (false). | crates/tessera-config/src/persistence.rs:59 |
float-small-windows |
boolean | true |
Whether windows smaller than small-window-size float automatically. The size judged is the one a window has on its own, never the tile Tessera gave it. | crates/tessera-config/src/persistence.rs:61 |
small-window-size |
integer (0..=u32::MAX) | 500 |
Size threshold in pixels for float-small-windows; non-positive values fall back to 500. | crates/tessera-config/src/persistence.rs:64 |
screen-padding-top |
integer (0..=u32::MAX) | 0 |
Padding in pixels between the top screen edge and the tiling area. | crates/tessera-config/src/persistence.rs:70 |
screen-padding-right |
integer (0..=u32::MAX) | 0 |
Padding in pixels between the right screen edge and the tiling area. | crates/tessera-config/src/persistence.rs:76 |
screen-padding-bottom |
integer (0..=u32::MAX) | 0 |
Padding in pixels between the bottom screen edge and the tiling area. | crates/tessera-config/src/persistence.rs:82 |
screen-padding-left |
integer (0..=u32::MAX) | 0 |
Padding in pixels between the left screen edge and the tiling area. | crates/tessera-config/src/persistence.rs:88 |
Preferences
User preferences governing mouse behavior, HUD overlays, notification mechanisms, overflow handling, and daemon lifecycle.
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
hud-duration-ms |
integer (0..=u32::MAX) | 600 |
How long the HUD stays on screen, in milliseconds; 600..=5000, an out-of-range value is reported and read as 600. | crates/tessera-config/src/preferences.rs:345 |
window-resize-step |
float (1.0..=100.0) | 5.0 |
Percentage step for keyboard window resize operations in 1..=100. | crates/tessera-config/src/preferences.rs:343 |
mouse-follows-focus |
boolean | false |
Whether the mouse cursor moves to the center of the newly focused window. | crates/tessera-config/src/preferences.rs:346 |
focus-follows-mouse |
boolean | false |
Whether moving the mouse over a window shifts active focus to it. | crates/tessera-config/src/preferences.rs:347 |
mouse-swaps-windows |
boolean | false |
Whether dragging a window onto another swaps their positions in the layout. | crates/tessera-config/src/preferences.rs:348 |
mouse-resizes-windows |
boolean | false |
Whether dragging window borders resizes tiled window panes. | crates/tessera-config/src/preferences.rs:349 |
enables-layout-hud |
boolean | true |
Whether the layout HUD overlay appears when cycling or selecting layouts. | crates/tessera-config/src/preferences.rs:350 |
enables-layout-hud-on-space-change |
boolean | true |
Whether the layout HUD overlay appears when switching workspaces. | crates/tessera-config/src/preferences.rs:351 |
enables-window-count-hud |
boolean | false |
Whether the layout HUD overlay shows the count of managed windows. | crates/tessera-config/src/preferences.rs:352 |
debug-layout-info |
boolean | false |
Whether verbose layout geometry information is logged. | crates/tessera-config/src/preferences.rs:353 |
restore-layouts-on-launch |
boolean | true |
Whether last-used layout assignments per output are restored at startup. | crates/tessera-config/src/preferences.rs:354 |
active-layout |
string | none | Layout key in use (for example wide), saved when a layout is selected so the next start resumes on it without reordering the layouts cycle; empty or absent means the first layout of the cycle. A layout outside the cycle is used as it is and leaves the cycle untouched; a key this build does not know is reported, kept in the file and starts on the first layout of the cycle; a value that is not text is reported, kept, and read as empty. | crates/tessera-config/src/preferences.rs:357 |
new-windows-to-main |
boolean | false |
Whether newly opened windows are inserted into the main pane. | crates/tessera-config/src/preferences.rs:358 |
follow-space-thrown-windows |
boolean | true |
Whether workspace focus follows windows sent to another workspace. | crates/tessera-config/src/preferences.rs:359 |
disable-padding-on-builtin-display |
boolean | false |
Whether screen padding is skipped on the internal laptop screen. | crates/tessera-config/src/preferences.rs:360 |
hide-menu-bar-icon |
boolean | false |
Whether the StatusNotifier / system tray icon is hidden. | crates/tessera-config/src/preferences.rs:361 |
ignore-menu-bar |
boolean | false |
Whether panels, struts, and docks are ignored during tiling calculation. | crates/tessera-config/src/preferences.rs:362 |
language |
string | auto |
Interface language: auto (TESSERA_LANG, then LC_ALL, LC_MESSAGES and LANG) or a shipped locale such as en or pt-BR; an unknown value is reported, kept, and read as auto. | crates/tessera-config/src/preferences.rs:365 |
ui-style |
enum (auto, gtk, adwaita, qt, appkit, win32) |
auto |
Look of the interface: auto lets the session choose the best available provider (libadwaita or GTK, Qt on Qt desktops, or a native provider); or name a provider. TESSERA_UI overrides it; an unknown or unavailable value is reported and read as auto. Applied at the next start. | crates/tessera-config/src/preferences.rs:368 |
notification-style |
enum (system, hud) |
system |
Notification mechanism for user feedback (system or hud). | crates/tessera-config/src/preferences.rs:366 |
window-decorations |
enum (keep, hide-tiled) |
keep |
Window-manager title bars and borders: keep them on every window, or hide them on tiled windows (floating windows keep theirs). | crates/tessera-config/src/preferences.rs:377 |
overflow-policy |
enum (move-to-output, float, shrink-neighbors, minimize) |
move-to-output |
Action taken when tiled windows exceed maximum layout capacity. | crates/tessera-config/src/preferences.rs:371 |
overflow-hud-warning |
boolean | false |
Whether a HUD alert is displayed when the overflow policy triggers. | crates/tessera-config/src/preferences.rs:373 |
per-workspace-layouts |
boolean | true |
Whether each global workspace remembers its selected layout. | crates/tessera-config/src/preferences.rs:375 |
mcp-enabled |
boolean | false |
Whether the embedded MCP server accepts AI agents; the agent can see and, in control mode, change the desktop. The tessera mcp bridge the agent runs is built for Linux only. |
crates/tessera-config/src/preferences.rs:379 |
mcp-mode |
enum (read-only, control) |
read-only |
What an MCP agent may do: read-only inspects windows; control may also move, focus, float and stick them. | crates/tessera-config/src/preferences.rs:381 |
mcp-allowed-tools |
list | [] |
MCP tool names to expose; empty means every tool the mode allows. Never enables a tool the mode forbids. | crates/tessera-config/src/preferences.rs:383 |
Layout Configuration
Keys governing layout cycling algorithms and output-specific layout persistence.
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
layouts |
list | ["tall", "wide", "fullscreen", "column"] |
Ordered list of layout algorithm keys cycled through by the user. | crates/tessera-config/src/persistence.rs:35 |
tessera-output-layouts |
mapping (output: layout) |
none | Map of output connector names to layout keys for persistent assignments. | crates/tessera-config/src/lib.rs:76 |
tessera-workspace-layouts |
mapping | none | Map of global workspace indices to their selected layout keys. | crates/tessera-config/src/lib.rs:78 |
workspace-assignments |
list | none | Ordered window rules assigning newly observed windows to workspaces. | crates/tessera-config/src/lib.rs:84 |
Modifier Groups
Defines the modifier combinations mapped to chord identifiers (mod1, mod2, mod3, mod4).
Supported modifiers: option (alt), shift, control (ctrl), command (super).
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
mod1 |
list | ["option", "shift"] |
Modifier keys assigned to the primary mod1 chord group. | crates/tessera-config/src/bindings.rs:185 |
mod2 |
list | ["option", "shift", "control"] |
Modifier keys assigned to the secondary mod2 chord group. | crates/tessera-config/src/bindings.rs:186 |
mod3 |
list | none | Modifier keys assigned to the tertiary mod3 chord group. | crates/tessera-config/src/bindings.rs:218 |
mod4 |
list | none | Modifier keys assigned to the quaternary mod4 chord group. | crates/tessera-config/src/bindings.rs:218 |
Command Bindings
Default keyboard shortcuts for window management, navigation, pane sizing, and layout cycling.
Bindings map a modifier group (mod) and a key symbol (key), or can be set to false to disable.
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
cycle-layout |
mapping (mod, key) or false |
{"mod": "mod1", "key": "space"} |
Cycle forward to the next configured layout algorithm. | crates/tessera-config/src/schema/keys.rs |
cycle-layout-backward |
mapping (mod, key) or false |
{"mod": "mod2", "key": "space"} |
Cycle backward to the previous configured layout algorithm. | crates/tessera-config/src/schema/keys.rs |
select-tall-layout |
mapping (mod, key) or false |
{"mod": "mod1", "key": "a"} |
Switch directly to the tall layout. | crates/tessera-config/src/schema/keys.rs |
select-wide-layout |
mapping (mod, key) or false |
{"mod": "mod1", "key": "s"} |
Switch directly to the wide layout. | crates/tessera-config/src/schema/keys.rs |
select-fullscreen-layout |
mapping (mod, key) or false |
{"mod": "mod1", "key": "d"} |
Switch directly to the fullscreen layout. | crates/tessera-config/src/schema/keys.rs |
select-column-layout |
mapping (mod, key) or false |
{"mod": "mod1", "key": "f"} |
Switch directly to the column layout. | crates/tessera-config/src/schema/keys.rs |
focus-screen-ccw |
mapping (mod, key) or false |
{"mod": "mod1", "key": "p"} |
Move focus to the counter-clockwise screen. | crates/tessera-config/src/bindings.rs:185 |
focus-screen-cw |
mapping (mod, key) or false |
{"mod": "mod1", "key": "n"} |
Move focus to the clockwise screen. | crates/tessera-config/src/bindings.rs:185 |
shrink-main |
mapping (mod, key) or false |
{"mod": "mod1", "key": "h"} |
Decrease the ratio of the primary layout pane. | crates/tessera-config/src/schema/keys.rs |
expand-main |
mapping (mod, key) or false |
{"mod": "mod1", "key": "l"} |
Increase the ratio of the primary layout pane. | crates/tessera-config/src/schema/keys.rs |
increase-main |
mapping (mod, key) or false |
{"mod": "mod1", "key": ","} |
Increase the number of windows placed in the main pane. | crates/tessera-config/src/schema/keys.rs |
decrease-main |
mapping (mod, key) or false |
{"mod": "mod1", "key": "."} |
Decrease the number of windows placed in the main pane. | crates/tessera-config/src/schema/keys.rs |
focus-ccw |
mapping (mod, key) or false |
{"mod": "mod1", "key": "j"} |
Cycle window focus counter-clockwise within the workspace. | crates/tessera-config/src/bindings.rs:717 |
focus-cw |
mapping (mod, key) or false |
{"mod": "mod1", "key": "k"} |
Cycle window focus clockwise within the workspace. | crates/tessera-config/src/bindings.rs:709 |
focus-main |
mapping (mod, key) or false |
{"mod": "mod1", "key": "m"} |
Focus the window located in the main pane. | crates/tessera-config/src/schema/keys.rs |
swap-screen-ccw |
mapping (mod, key) or false |
{"mod": "mod2", "key": "h"} |
Move active window to the counter-clockwise screen. | crates/tessera-config/src/schema/keys.rs |
swap-screen-cw |
mapping (mod, key) or false |
{"mod": "mod2", "key": "l"} |
Move active window to the clockwise screen. | crates/tessera-config/src/schema/keys.rs |
swap-ccw |
mapping (mod, key) or false |
{"mod": "mod2", "key": "j"} |
Swap active window with counter-clockwise neighbor. | crates/tessera-config/src/schema/keys.rs |
swap-cw |
mapping (mod, key) or false |
{"mod": "mod2", "key": "k"} |
Swap active window with clockwise neighbor. | crates/tessera-config/src/schema/keys.rs |
swap-main |
mapping (mod, key) or false |
{"mod": "mod1", "key": "enter"} |
Promote active window into the main layout pane. | crates/tessera-config/src/schema/keys.rs |
throw-space-left |
mapping (mod, key) or false |
{"mod": "mod2", "key": "left"} |
Send active window to the previous workspace. | crates/tessera-config/src/bindings.rs:192 |
throw-space-right |
mapping (mod, key) or false |
{"mod": "mod2", "key": "right"} |
Send active window to the next workspace. | crates/tessera-config/src/bindings.rs:192 |
toggle-float |
mapping (mod, key) or false |
{"mod": "mod1", "key": "t"} |
Toggle floating state of the active window. | crates/tessera-config/src/bindings.rs:725 |
toggle-tiling |
mapping (mod, key) or false |
{"mod": "mod2", "key": "t"} |
Toggle active tiling management on or off. | crates/tessera-config/src/schema/keys.rs |
display-current-layout |
mapping (mod, key) or false |
{"mod": "mod1", "key": "i"} |
Trigger the HUD to display the current layout. | crates/tessera-config/src/schema/keys.rs |
reevaluate-windows |
mapping (mod, key) or false |
{"mod": "mod1", "key": "z"} |
Re-query windows and re-evaluate layout geometry. | crates/tessera-config/src/schema/keys.rs |
toggle-focus-follows-mouse |
mapping (mod, key) or false |
{"mod": "mod2", "key": "x"} |
Toggle the focus-follows-mouse preference. | crates/tessera-config/src/schema/keys.rs |
relaunch-controller |
mapping (mod, key) or false |
{"mod": "mod2", "key": "z"} |
Relaunch the background controller daemon process. | crates/tessera-config/src/schema/keys.rs |
swap-screen-1 |
mapping (mod, key) or false |
false |
Move active window to screen index 1; disabled by default. | crates/tessera-config/src/schema/keys.rs |
swap-screen-2 |
mapping (mod, key) or false |
false |
Move active window to screen index 2; disabled by default. | crates/tessera-config/src/schema/keys.rs |
swap-screen-3 |
mapping (mod, key) or false |
false |
Move active window to screen index 3; disabled by default. | crates/tessera-config/src/schema/keys.rs |
swap-screen-4 |
mapping (mod, key) or false |
false |
Move active window to screen index 4; disabled by default. | crates/tessera-config/src/schema/keys.rs |
swap-screen-5 |
mapping (mod, key) or false |
false |
Move active window to screen index 5; disabled by default. | crates/tessera-config/src/schema/keys.rs |
Screen Shortcuts
Keyboard shortcuts for focusing and moving active windows across multi-monitor displays (indices 1 through 5).
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
focus-screen-1 |
mapping (mod, key) or false |
{"mod": "mod1", "key": "w"} |
Focus screen index 1. | crates/tessera-config/src/bindings.rs:185 |
focus-screen-2 |
mapping (mod, key) or false |
{"mod": "mod1", "key": "e"} |
Focus screen index 2. | crates/tessera-config/src/bindings.rs:185 |
focus-screen-3 |
mapping (mod, key) or false |
{"mod": "mod1", "key": "r"} |
Focus screen index 3. | crates/tessera-config/src/bindings.rs:185 |
focus-screen-4 |
mapping (mod, key) or false |
{"mod": "mod1", "key": "q"} |
Focus screen index 4. | crates/tessera-config/src/bindings.rs:185 |
focus-screen-5 |
mapping (mod, key) or false |
{"mod": "mod1", "key": "g"} |
Focus screen index 5. | crates/tessera-config/src/bindings.rs:185 |
throw-screen-1 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "w"} |
Send active window to screen index 1. | crates/tessera-config/src/bindings.rs:186 |
throw-screen-2 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "e"} |
Send active window to screen index 2. | crates/tessera-config/src/bindings.rs:186 |
throw-screen-3 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "r"} |
Send active window to screen index 3. | crates/tessera-config/src/bindings.rs:186 |
throw-screen-4 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "q"} |
Send active window to screen index 4. | crates/tessera-config/src/bindings.rs:186 |
throw-screen-5 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "g"} |
Send active window to screen index 5. | crates/tessera-config/src/bindings.rs:186 |
Workspace Shortcuts
Keyboard shortcuts for throwing active windows to workspaces (workspaces 1 through 10).
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
throw-space-1 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "1"} |
Send active window to workspace 1. | crates/tessera-config/src/bindings.rs:192 |
throw-space-2 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "2"} |
Send active window to workspace 2. | crates/tessera-config/src/bindings.rs:192 |
throw-space-3 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "3"} |
Send active window to workspace 3. | crates/tessera-config/src/bindings.rs:192 |
throw-space-4 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "4"} |
Send active window to workspace 4. | crates/tessera-config/src/bindings.rs:192 |
throw-space-5 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "5"} |
Send active window to workspace 5. | crates/tessera-config/src/bindings.rs:192 |
throw-space-6 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "6"} |
Send active window to workspace 6. | crates/tessera-config/src/bindings.rs:192 |
throw-space-7 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "7"} |
Send active window to workspace 7. | crates/tessera-config/src/bindings.rs:192 |
throw-space-8 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "8"} |
Send active window to workspace 8. | crates/tessera-config/src/bindings.rs:192 |
throw-space-9 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "9"} |
Send active window to workspace 9. | crates/tessera-config/src/bindings.rs:192 |
throw-space-10 |
mapping (mod, key) or false |
{"mod": "mod2", "key": "0"} |
Send active window to workspace 10. | crates/tessera-config/src/bindings.rs:192 |
Tiling Activation Shortcuts
Explicit keyboard shortcuts to enable or disable automatic tiling management. Disabled by default.
| Key | Type | Default | Description / Effect | Implementation |
|---|---|---|---|---|
enable-tiling |
mapping (mod, key) or false |
false |
Explicitly enable tiling management; disabled by default. | crates/tessera-config/src/schema/keys.rs |
disable-tiling |
mapping (mod, key) or false |
false |
Explicitly disable tiling management; disabled by default. | crates/tessera-config/src/schema/keys.rs |