TUI Overview

At a high level, the TUI only has one job, which is all about mapping make targets onto tmux panes. Simple right? But the interesting part is, everything is a target, so it's very quick and easy to treat containers or existing automation as UI elements, and stick them together as an application. A looping group of targets? That's a target. A containerized sub-UI? That's a target. A console-friendly selector widget? Maybe even a whole x11 application or xsession?? Target, target, target.

TUI Gallery

For the impatient, here's a small gallery that show-cases the type of stuff you can do.

( Click any image to make it bigger. )

For a quickstart, you might like to:

1. Run a simple test to get a look at the TUI yourself. Try running ./compose.mk tux.demo
2. Skim at least the layout basics on this page
3. Jump to the first TUI tutorial, then follow the sequence.

Other resources:

• For low-level API reference, see the tux.* targets.
• For TUI-related stand-alone tools, see the loadf docs and the tool wrappers docs.
• See also the user input / interactivity section of the standard library.

Batteries Included

Besides a dockerized tmux, the basic pre-configured components of the TUI are things like tmuxp for dynamic session management, and overridable defaults for tmux themes, tmux plugins, keybindings, etc.

These components are configurable, but not something that you necessarily have to think about. Some notable effects of the "sane defaults" policy include:

• Click to open a new pane, or click to exit
• Leave the TUI by hitting the escape key (if the embedded apps don't intercept the key)
• Advanced layouts like spiral & fibbonacci, using dwindle
• Status bar including details like user, pid, & working-dir

These elements, plus access to other tools like gum and chafa, are all setup in the embedded compose.mk:tux container, which is built and used only on demand.

Default Keybindings

The TUI ships with some default keybindings that are aimed at keeping things pretty user-friendly even for those who are not already familiar with tmux.

Note that the usual limitations for shortcuts apply! There's no way to guarantee these defaults won't collide with whatever existing applications you're trying to stitch together, with your terminal or with your window-manager.

Layout Basics

We'll start by showing how to map targets onto a specific pane orientation, using the tux.open target-family. For mapped targets, we'll use flux.ok, which has no arguments and simply succeeds without doing anything.

# Specify a horizontal layout and pass in 3 targets
$ ./compose.mk tux.open.horizontal/flux.ok,flux.ok,flux.ok

Running this command shows some log messages detailing the startup process and the first time it runs you'll see the TUI bootstrapping itself (i.e. building the necessary support containers for running tmux). (Afterwards it will be cached, so startup is much faster.)

After it starts, you'll see an interface like this, and it ran the flux.ok target for you, once in each pane.

# Other equivalent forms
$ layout=horizontal ./compose.mk tux.open/flux.ok,flux.ok,flux.ok
$ layout=h ./compose.mk tux.open/flux.ok,flux.ok,flux.ok

Vertical Orientation

For controlling the default orientation, tux.open.vertical of course works in a similar manner as you can see below.

# Specifies a vertical layout, and pass in 2 targets
$ ./compose.mk tux.open.vertical/flux.ok,flux.ok

# Other equivalent forms 
$ layout=vertical ./compose.mk tux.open/flux.ok,flux.ok
$ layout=v ./compose.mk tux.open/flux.ok,flux.ok

Spiral Orientation

The main alternative to "horizontal" and "vertical" is called "spiral", and it looks like this:

Next Steps

These 3 layouts are enough for most use-cases, but compose.mk actually supports whatever tmux does and also whatever dwindle supports.

Of course, flux.ok is not very interesting, but it is the simplest target. We'll move into more practical examples in the following sections, and almost everything else we'll look at is some variation of the principles above.