tilemux

An i3-like tiling layer for tmux, in a single config file. No plugins, no helper scripts, no dependencies. Design target is tmux 3.6.

Windows are workspaces, panes are tiles, and every binding is on Alt so no prefix is needed. Ctrl+Space is kept as the tmux prefix so nothing is out of reach.

Install

cp tilemux.conf ~/.tilemux.conf

Then add an alias to your shell rc:

alias tilemux='tmux -L tilemux -f ~/.tilemux.conf'

tilemux new -A -s main      start it, or attach if already running
tilemux ls                  list sessions
tilemux kill-server         stop it

tilemux runs on its own socket, so it has its own server and its own sessions and the tmux you already use is untouched. The socket is what does the isolating: -f is read only when a server starts, so on its own it would be ignored by an already running tmux.

Alt+? lists every key. The rules are commented in tilemux.conf next to the bindings that implement them, so this file only shows what they do.

The model

tmux keeps a layout as a tree but exposes only pane geometry to its formats, so the bindings work to one explicit model instead:

a window is a row of columns, and each column is a stack of panes

Alt+Shift+Left/Right moves a pane between columns. It leaves its own column and joins the neighbouring one:

+----+----+          +----+----+
| a  | C  |          |    | a  |
+----+----+    ->    |    +----+
| B  | D  |          | B  | C  |
+----+----+          |    +----+
                     |    | D  |
                     +----+----+

Alt+Shift+Up/Down reorders a pane inside the column it is already in:

+----+----+          +----+----+
| a  | C  |          | B  | C  |
+----+----+    ->    +----+----+
| B  | D  |          | a  | D  |
+----+----+          +----+----+

At the edge of the window there is no neighbour to move to, so the pane leaves its column and becomes a column of its own, or a full-width row going up or down. This is how a layout is restructured without presets:

+----+----+          +--+--+----+
| A  | C  |          |A |  |    |
+----+----+    ->    +--+ C|  d |
| B  | d  |          |B |  |    |
+----+----+          +--+--+----+

Alt+m and a direction is the way back in. Moving pushes panes apart, and a pane that is a whole column swaps with its neighbours instead of joining them, so merging needs a key of its own:

+---+---+---+          +---+-------+
|   |   |   |          |   |   B   |
| A | B | c |    ->    | A +-------+
|   |   |   |          |   |   c   |
+---+---+---+          +---+-------+

Debugging

Reload, then look at what a key runs and what the rules are reading:

tilemux source-file ~/.tilemux.conf
tilemux list-keys -T root | grep 'M-L'
tilemux display -p '#{window_layout}'
tilemux list-panes -F '#{pane_index} #{pane_left},#{pane_top}'

Watch for #{>:a,b}: it compares strings. Numbers need #{e|>:a,b}.

To try a binding without disturbing the tmux you work in, run a second server on its own socket and attach to it from a pane of the first. send-keys writes to that pane, so the attached client reads the keys and the binding fires:

tmux -L test -f ./tilemux.conf new-session -d -s w -x 200 -y 48
tmux -L ctl -f /dev/null new-session -d -x 200 -y 49 \
	'tmux -L test attach -t w'
tmux -L test split-window -h
tmux -L test select-pane -t 1
tmux -L ctl send-keys -t 0 M-L
tmux -L test list-panes -F '#{pane_index} #{pane_left} #{pane_active}'
tmux -L test kill-server

Killing the test server ends the attach, and the ctl server with it.

Caveats

A 2x2 built as columns of rows and one built as rows of columns look identical on screen. Geometry cannot tell them apart, so both behave as columns of rows.

A pane that spans the window swaps with a neighbour instead of pushing past it, and tmux picks which neighbour by geometry, so a full-height column can trade places with one pane of the stack beside it. Alt+m puts it back.

A pane leaving a stack does not make the rest rebalance; the neighbour absorbs the space, as it does when a pane is killed. Alt+r then = evens a container out.

Copy mode has its own key table. With the default emacs mode-keys it takes seventeen of these keys for itself: Alt+1 to Alt+9, Alt+Up, Alt+Down, Alt+b, Alt+f, Alt+l, Alt+m, Alt+r and Alt+v. Those do not reach tilemux while a pane is in copy mode, and every other key falls through and works. setw -g mode-keys vi avoids the clash entirely.

Alt+? needs a terminal of at least 76x23. Below that tmux refuses the popup and says so in the status line; there is no smaller help.

Alt+Shift with a number assumes the shifted symbols of a US layout (!@#$%^&*()).

License

BSD 3-Clause. See LICENSE.