A Tabbed Tiling Wayland Compositor

Tabby started life as a X11 window manager and remained that way up through version 1.0. It's now on a journey of recreation in wayland. Version 1.1 was never a tagged release as it was experimental and full of shortcuts that would not have worked on more diverse systems from my own development machine. Version 1.2 should be viable for more general use, though there will still be some growing pains as Tabby is in active development. Feel free to see the "Roadmap" file to see what goals are currently on my radar.


Tabby provides it's own bar with optional left and right status regions and window title bars in the middle. All three regions are highly configurable both through scripts / programs you can run to provide input to each status region and through format strings that you can adjust to completely change the color and layout of any of the text in the statuses or title regions. This may be best understood by seeing the examples and comments in the default config file.

Below is a simple script I use to display date, time, and optionally battery (if low) and email (if any new) information in the right status area of tabby:


while :; do

read n0 < /sys/class/power_supply/BAT0/energy_now
read n1 < /sys/class/power_supply/BAT1/energy_now
read f0 < /sys/class/power_supply/BAT0/energy_full
read f1 < /sys/class/power_supply/BAT1/energy_full

bat=$((100 * (n0+n1) / (f0+f1)))
[ $bat -lt 16 ] && bstr=" {bg=3}{fg=0} $bat"
[ $bat -lt 6 ] && bstr=" {bg=1}{fg=0} $bat"

nmail=$(find /path/to/mail/Inbox/new/ -type f | wc -l)

[ $nmail -gt 0 ] && mail=" {bg=4}{fg=0} $nmail"

date "+{fg=7} %m.%d {fg=4}%H:%M ${mail}${bstr} "

sleep 5



Each tiling mode is identified by the mode number which is the maximum number of client windows it tiles the screen with. If there are more than this number of client windows, the remainder will be stacked in the last position (and can be cycled through with focusrel/focusto commands). If there are fewer clients than the mode is designed for, Tabby will fall back to a smaller mode number appropriate for the number of availbale clients.

In otherwords, if you define 5 modes and at runtime select mode 1, then only one surface (i.e., window) will be visible regardless of how many client surfaces are mapped. If you switch to mode 3, then up to three client surfaces will be visible; if only one is mapped, then it will be tiled as in mode 1 until another is mapped at which point they'll be tiled as in mode 2, and when another is mapped they'll be displayed as in mode 3, if yet another is mapped, only three surfaces will be tiled due to mode 3 being selected.

The tiling positions are designed to be highly configurable and are defined in a single user-selectable file. The modes defined in the default tiling.alo file are described below followed by notes on the tiling file syntax so you can create your own.

Default Modes

Each mode is defined by a list of placement specifiers. Mode 1 has only one placement specifier (and while it could be anything, it really only makes sense for this to be the maximized / full-useable-area specifier which would be called "monocle" in dwm/dwl). Mode 2 has two specifiers; mode 3 has three, etc.

Placement specifiers (P in the table below) are indices into a list of floating point number quartets specifying the x, y, w, and h of a surface. The default tiling.algo file defines these placements as positions in four different arrangement patterns as described below:

Pattern Name P Position Description
Loner 0 Maximized / monocle
Halvsies 1 Left half
2 Upper half
3 Right half
4 Lower half
Quartets 5 Upper left
6 Upper right
7 Lower right
8 Lower left
Sixpack 9 Upper 1/3, left 1/2
10+ See below
The 12 positions of the "sixpack" pattern:
┌──────┬──────┐  ┌───┬───┬───┐
│  09  │  10  │  │ 1 │ 1 │ 1 │
├──────┼──────┤  │ 5 │ 6 │ 7 │
│  14  │  11  │  ├───┼───┼───┤
├──────┼──────┤  │ 2 │ 1 │ 1 │
│  13  │  12  │  │ 0 │ 9 │ 8 │
└──────┴──────┘  └───┴───┴───┘

As seen in both the halvsies and sixpack patterns, there can be more than one way to divide up a screen into N parts. Each way of splitting the screen into N parts defines different positions and any / all of them can be used interchangeably. For a split screen view you may have a tiling mode defined as "1 3" for left / right or as "2 4" for top/bottom. While "1 2" does not sound reasonable or appealing to me, tabby would not prevent you from specifying such a layout if you liked it (that'd be one window on the left half, and one on the upper half so they partially overlap while the lower right is empty).

Or course you can also mix and match different algorithms within a tiling mode in order to create modes similar to dwl/dwm's rstack or bstack (of course you could also create an lstack or tstack too if you want!).

While there is great flexibility in how you define your tiling modes, there is a limitation in that you can only specify one way of tiling N windows. So you cannot toggle between rstack and bstack views for 4 windows (but you can configure tabby to use an rstack for 3 and a bstack for 4).

The first line of numbers in the tiling algorith file also defines the monitor on which each window should be placed in a multi-monitor setup. This behavior is not yet implemented and these monitor values are currently ignored.

Tiling .algo File Format

There are three sections in the file labeled in the default as 'monitors', 'modes', and 'placements'. The content of these labels is ignored, but there must be a single non-numeric word or token at the start of each of the three sections.

The first two sections are white-space-delineated lists of integers. In order to define n modes, each of these first two lists should contain a number of entries equal to the nth triangular number (i.e., n * (n + 1) / 2). The values in the first list are a monitor indices (or just all zeros for a single-monitor system) indicating on which monitor each surface should be placed in each mode. The values in the second list are indices into the placement list indicating where in monitor-relative coordinates each surface should be tiled.

The third list is made up of blocks of four floating point values which are monitor-relative (zero to one inclusive) coordinates for the x and y position and width and height of each placement.


Tabby can be built with the included makefile, but the wayland protocol source files must be prepared first:

make protocols

A PKGBUILD is also provided for archlinux and related distros.


Please feel free to report bugs to the tracker on the project homepage. If you are viewing this README online, you are looking at the project homepage, otherwise please see here.