Organize your console with tmuxinator

Author: Solène
Date: 17 May 2024
Tags: unix terminal portoftheweek

Introduction

This article is about the program tmuxinator, a tool to script the generation of tmux sessions from a configuration file.

tmuxinator official project website on GitHub

This program is particularly useful when you have repeated tasks to achieve in a terminal, or if you want to automate your tmux session to save your fingers from always typing the same commands.

tmuxinator is packaged in most distributions and requires tmux to work.

Configuration

tmuxinator requires a configuration file for each "session" you want to manage with it. It provides a command line parameter to generate a file from a template:

$ tmuxinator new name_here

By default, it will create the yaml file for this project in `$HOME/.config/tmuxinator/name_here.yml`, if you want the project file to be in a directory (to make it part of a versioned project repository?), you can add the parameter `--local`.

Real world example

Here is a tmuxinator configuration file I use to automatically do the following tasks, the commands include a lot of monitoring as I love watching progress and statistics:

update my ports tree using git before any other task
run a script named dpb.sh
open a shell and cd into a directory
run an infinite loop displaying ccache statistics
run an infinite loop displaying a MFS mount point disk usage
display top
display top for user _pbuild

I can start all of this using `tmuxinator start dpb`, or stop only these "parts" of tmux with `tmuxinator stop dpb` which is practical when using tmux a lot.

Here is my file `dpb.yml`:

name: dpb
root: ~/

# Runs on project start, always
on_project_start: cd /usr/ports && doas -u solene git pull -r

windows:
  - dpb:
      layout: tiled
      panes:
        - dpb:
          - cd /root/packages/packages
          - ./dpb.sh -P list.txt -R
        - watcher:
          - cd /root/logs
          - ls -altrh locks
          - date
        - while true ; do clear && env CCACHE_DIR=/build/tmp/pobj/.ccache/ ccache -s ; sleep 5 ; done
        - while true ; do df -h /build/tmp/pobj_mfs/ | grep % ; sleep 10 ; done
        - top
        - top -U _pbuild

Going further

Tmuxinator could be used to ssh into remote servers, connect to IRC, open your email client, clean stuff, there are no limits.

This is particularly easy to configure as it does not try to run commands, but only send the keys to each tmux panes, which mean it will send keystrokes like if you typed them. In the example above, you can see how the pane "dpb" can cd into a directory and then run a command, or how the pane "watcher" can run multiple commands and leave the shell as is.

Conclusion

I knew about tmuxinator for a while, but I never gave it a try before this week. I really regret not doing it earlier. Not only it allows me to "script" my console usage, but I can also embed some development configuration into my repositories. While you can use it as an automation method, I would not rely too much on it though, it only types blindly on the keyboard.