User guide

Home · Installation · Layouts · Configuration · Platform support

Day-to-day use of Tessera: starting it, switching layouts, driving windows from the keyboard, and finding the right knob when something should behave differently. Reference material lives on other pages and is linked rather than repeated.

What Tessera is (and is not)

• Tessera is a tiling controller. It decides where windows should go and asks the window manager already running in your session to move and resize them.
• It is not a window manager. On the reference setup, Xfwm4 keeps drawing title bars, handling Alt+Tab and owning workspaces.
• The only profile with a real target is XFCE on X11 with xfwm4 4.20.0, and even that is marked implemented-unverified in docs/compatibility/support-manifest.yaml. Plasma Wayland is experimental; GNOME Wayland, macOS and Windows 11 are blocked. See Platform support before expecting anything outside XFCE/X11.

Start Tessera

One controller runs per session; launching tessera again does not create a second one.

Override a few settings for one run with --tiling-enabled / --tiling-disabled, --window-margins / --no-window-margins, --window-max-count <N> and --window-margin-size <N>. They only apply to starting the app, not to debug or service commands.

Start at login

Pick one of the two methods; do not combine them.

1. XDG autostart. The shipped entry org.xfce.Tessera-autostart.desktop runs tessera --autostart in XFCE sessions only (OnlyShowIn=XFCE). The tray’s Start at login checkbox toggles it.

2. systemd user service.

   tessera service install   # writes the unit; refuses to clobber a customised one
   tessera service enable    # start at every graphical login
   tessera service start     # start now
   tessera service status    # add --json for machine-readable output

   The other verbs are stop, disable, uninstall, reload and restart. Tessera only touches systemd when you run one of these.

A configuration reload without a restart: systemctl --user reload tessera, pkill -HUP tessera, or the Relaunch the controller shortcut (Alt+Shift+Ctrl+Z).

Inspect what Tessera sees

These commands are headless: no window opens, and they talk to the session directly.

--debug-info and debug windows --redact-window-titles are safe to paste in a bug report. To report a problem, open an issue at https://github.com/fabioluciano/tessera/issues with that output. To watch live logs: RUST_LOG=debug tessera --autostart.

The preferences window has a Diagnostics page with the same information, a list of windows Tessera could not place, and a Copy debug info button. The tray menu has Copy report too.

Layouts and cycling

A layout decides where each tiled window goes. Tessera has 18 built in, from tall and wide to bsp and grid; pictures and descriptions are on Layouts, and you can write your own in JavaScript (Custom layouts).

• Which layouts are in the cycle is the layouts list in tessera.yml (or the Layouts page of the preferences). The first entry is the default. Out of the box the list is tall, wide, fullscreen, column.
• Cycle: Alt+Shift+Space goes forward, Alt+Shift+Ctrl+Space backward.
• Jump: Alt+Shift+A tall, S wide, D fullscreen, F column. Any other layout can be bound as select-<layout>-layout (see Configuration).
• Main pane: Alt+Shift+H / L shrink or grow it; Alt+Shift+, / . change how many windows it holds. grid has no main pane.
• HUD: Alt+Shift+I shows the current layout on screen.
• Gaps and padding come from window-margins, window-margin-size and screen-padding-*.

Keyboard shortcuts

Shortcuts are built from two modifier groups, both editable:

Defaults come from crates/tessera-core/src/actions.rs and crates/tessera-config/src/bindings.rs.

Actions that exist but have no default key: toggle-sticky, enable-tiling, disable-tiling, toggle-new-windows-to-main, increase-window-max-count, decrease-window-max-count, command1…command4 (forwarded to custom layouts), swap-screen-1…5, throw-space-11…16 and select-<layout>-layout for layouts other than the four above. Bind one in tessera.yml:

toggle-sticky:
  mod: mod1
  key: y
select-grid-layout:
  mod: mod2
  key: g

The full list and syntax (including false to disable a binding) are in Configuration. You can also edit the chords on the Shortcuts page of the preferences.

Floating windows

A floating window keeps the position and size you give it, and the remaining windows tile around it.

Find the class to put in a rule with tessera debug apps, with the Choose… and Click a window helpers on the Rules page, or with xprop WM_CLASS and a click on the window.

floating:
  - pavucontrol
  - id: Firefox
    window-titles: ["Library", "Page Info"]

Some windows are never moved regardless of rules: docks and panels, modal dialogs, fixed-size windows, and fullscreen or minimized ones. tessera debug windows shows the reason in the UNMANAGED_REASON column. The matching rules and every key are in Configuration.

Monitors and workspaces

• Each monitor is tiled using its own work area, so the XFCE panel is respected. Plugging or unplugging a monitor re-lays-out the windows.
• Move focus between screens with Alt+Shift+N / P or W E R Q G; move a window with the Alt+Shift+Ctrl versions.
• Move a window between workspaces with Alt+Shift+Ctrl+1…0 or Left / Right.
• A layout per workspace is on by default (per-workspace-layouts: true): Tessera remembers each workspace’s layout, main-pane size and main-window count and restores them when you switch. Set it to false to use one layout everywhere.
• Send an application to a workspace automatically with workspace-assignments:, or on the Layouts page under Window workspace assignments. Rules apply to windows that open after the rule exists.

workspace-assignments:
  - id: Firefox
    workspace: 1        # counted from 0, so this is the second workspace

Tessera corrects only what it ordered. If the window manager refuses a placement, it retries once and then gives up, and the window appears under Problems found on the Diagnostics page. A window you move by hand is left alone. On a clean exit, windows go back to the frames they had when Tessera first saw them.

To hide title bars and borders of tiled windows, set window-decorations: hide-tiled (default keep) or use Window decorations on the General page.

Mouse

All four are off by default and are on the Mouse page of the preferences.

Preferences

Open it with tessera, Preferences… in the tray, or the application menu.

The pages are General, Appearance, Rules, Layouts, Shortcuts, Mouse, Diagnostics and About. Press Ctrl+K to search for a setting by name. Changes are written to the configuration file.

The interface language follows TESSERA_LANG, then the language key, then your locale variables; the look follows ui-style (or TESSERA_UI for one run). See Configuration.

Configuration

Settings live in a YAML file: $XDG_CONFIG_HOME/tessera/tessera.yml when that variable is an absolute path, otherwise ~/.config/tessera/tessera.yml on Linux and macOS. If the file is missing, built-in defaults are used. Unknown keys are kept, not deleted. Custom layout scripts go in layouts/*.js next to it.

Everything about keys, defaults and file layout is on Configuration.

Tray, notifications and HUD

On XFCE the tray (StatusNotifier) menu offers:

• the state, with an Organize windows checkbox
• Layout: with a submenu to pick one
• Start at login
• Preferences…, Reevaluate windows, Copy report
• Restore layouts from the configuration…, Restart Tessera, Quit Tessera

Hide the tray icon with hide-menu-bar-icon: true.

Feedback messages go through notification-style: system (desktop notifications, default) or hud (an on-screen overlay). The layout HUD is controlled by enables-layout-hud, enables-layout-hud-on-space-change, enables-window-count-hud and hud-duration-ms.

Other platforms

The repository has code for macOS and Windows backends and interfaces, and for GNOME and Plasma Wayland integrations, but per the support manifest none of them is a verified profile. Where a build has no matching provider, commands fail with one localized line on standard error and a non-zero exit status:

--help and --version always work. Do not rely on tiling outside XFCE/X11; check Platform support.

When something is wrong

Anything not covered: open an issue at https://github.com/fabioluciano/tessera/issues and attach tessera --debug-info.