tmuxp - a session manager for tmux that loads, freezes, and converts sessions via declarative YAML or JSON files.

The project is based on libtmux and is actively developed on GitHub. The idea is simple. Instead of manually opening five windows every morning and typing in commands, you define your working environment once as a file and load it with a single command.

What tmuxp Does

tmuxp manages tmux sessions based on configuration files. In them, you describe which windows and panes should be opened and which commands should be executed in them. When loading, tmuxp builds the session exactly as you defined it.

This works with YAML and JSON. tmuxp also supports the formats of tmuxinator and teamocil, which makes switching easier if you already use one of these solutions.

Installation

tmuxp can be installed in various ways. Depending on the system and preference, there are several options.

On Debian and Ubuntu it runs via apt.

sudo apt install tmuxp

For Manjaro

sudo pamac install tmuxp

Other installation methods are described on GitHub.

Loading a Session

The heart of tmuxp is the load command. You define a session in a YAML file and load it with it.

A simple example looks like this.

# yaml file
session_name: my-project
windows:
  - window_name: editor
    panes:
      - shell_command:
          - vim
      - shell_command:
          - git status

You save this file as my-project.yaml and then load it.

tmuxp load my-project.yaml

Explanation:

  1. tmuxp then builds a session with the name my-project.
  2. It contains a window named editor, which is split into two panes.
  3. In the first pane, vim runs
  4. in the second, git status is executed.

More Complex Configuration

tmuxp can do considerably more than just simple windows. You can define layouts, execute commands before all panes start, and equip multiple panes with different tasks.

An example with four panes and a predefined layout.

session_name: 4-pane-split
windows:
  - window_name: dev window
    layout: tiled
    shell_command_before:
      - cd ~/
    panes:
      - shell_command:
          - cd /var/log
          - ls -al | grep \.log
      - echo second pane
      - echo third pane
      - echo fourth pane

Explanation:

  1. The parameter shell_command_before executes a command in all panes before the actual commands start. In this case, each pane first switches to the home directory.
  2. The parameter layout determines how the panes are arranged.
  3. tiled means that all panes are distributed evenly.

Size Specifications

The layout Option

The central option for this is layout. You can either use a predefined name or a specific layout string that tmux itself generates.

Predefined layouts are easy to use but give you less control:

windows:
  - window_name: dev
    layout: main-horizontal
    panes:
      - vim
      - git status

Other common names are tiled, even-horizontal, and even-vertical.

Specific Sizes and Positions

If you want to define exactly how the panes are arranged, you must use the layout string from tmux. This string is an encoded description of the division and size of each cell.

  1. Manually build a tmux session with the desired pane divisions.
  2. Query the current layout:
tmux list-windows
  1. Copy the layout string (the long code after layout:) into your tmuxp YAML file.

An example of such a string looks like this:

layout: 382a,80x60,0,0[80x10,0,0,0,80x10,0,11,1,80x10,0,22,2,80x8,0,33,3]

The numbers encode the width x height and position of each pane. This is precise, but not particularly readable.

Alternative % for Simple Adjustments

If you only want to adjust the height of the main pane in layouts such as main-horizontal or main-vertical, you can use the main-pane-height option. This can be specified in lines or, since tmuxp 1.46.0, also in percent.

windows:
  - window_name: rust-study
    layout: main-horizontal
    options:
      main-pane-height: 67%
    panes:
      - vim
      - cargo run

This is often the more practical way if you only want to control the size ratio between the main and secondary panes.

Projects and Configuration Directories

tmuxp searches for configurations in various directories. If you place a file named .tmuxp.yaml or .tmuxp.json in a project folder, you can load it directly via the folder path.

tmuxp load path/to/my/project/

For user-wide configurations, tmuxp automatically searches several directories. This is practical if you want to load your sessions from anywhere without specifying the full path.

  • $TMUXP_CONFIGDIR, if set
  • $XDG_CONFIG_HOME, usually $HOME/.config/tmuxp/
  • $HOME/.tmuxp/

If your configuration is located under ~/.config/tmuxp/mysession.yaml, the following command is sufficient.

tmuxp load mysession

You can also load multiple sessions at the same time.

tmuxp load mysession ./another/project/

Or give the session its own name.

tmuxp load -s session_name ./mysession.yaml

Freezing Sessions (Saving)

Sometimes you have already built a tmux session and want to save it as a configuration. For this there is the freeze command.

tmuxp freeze session-name

tmuxp then creates a YAML or JSON file that describes the current state of the session. Layout, pane paths, window names, and session names are adopted. This is practical if you have built a session spontaneously and want to reproduce it later.

The tmuxp freeze command does not save the file in a fixed directory by default. Instead, you are asked where the file should be saved when you run it.

Where to Save

When you run tmuxp freeze session-name, tmuxp offers to save the state as a .yaml or .json file.

When running tmuxp freeze, you are interactively asked where the file should be saved. You can then specify the location or confirm a suggested path.

Storage Locations for Configurations

If you want to conveniently load your frozen session by name later, you should place it in one of the following directories:

  • ~/.tmuxp/ – the classic directory
  • ~/.config/tmuxp/ – the XDG standard path
  • Project-local – as .tmuxp.yaml or .tmuxp.json in the project folder

Specifying Your Own Path

You can also specify the storage location directly with the -o or --save-to parameter.

tmuxp freeze my-session -o /path/to/file.yaml

Converting Between Formats

If you want to convert a configuration from YAML to JSON or vice versa, you can do this with the convert command.

tmuxp convert filename

tmuxp shows you the new file and asks for confirmation. If you want to confirm the prompt automatically, you can use the -y parameter.

tmuxp convert -y filename

The tmuxp Shell

Since version 1.6.0 there is the command tmuxp shell. This starts a Python console that is preloaded with the current server, session, and window as libtmux objects.

tmuxp shell

This is useful if you want to script or automate tmux sessions.

Plugins and Extensions

tmuxp has a plugin system with which you can add your own behavior. This is interesting if you have special requirements that go beyond the standard functions.

A pre-load hook allows you to execute custom scripts before tmux is loaded. This can be used, for example, to install project dependencies.

Debugging

If something goes wrong when loading a session, you can write the output to a log file.

tmuxp load --log-file <log-file-name> .

For bug reports there is the command tmuxp debug-info, which collects system information.

tmuxp debug-info

Load in the Background

If you want to load a session without attaching to it directly, you can use the -d parameter.

tmuxp load -d mysession.yaml

This is practical if you want to prepare multiple sessions and decide later which one to use.

Conclusion

tmuxp is a tool that makes tmux considerably more pleasant for me. Instead of building the same session by hand every time, I define it once and load it with a single command. Or copy it to multiple machines so that I only have to define it once. This saves time and reduces errors.

I find the ability to freeze sessions particularly practical. If I have spontaneously built a session that I need more often, I simply save it as a configuration and have it ready immediately the next time.

Thanks to Markus from the Fediverse https://social.row-social.de/@markus, who brought it to my attention!

Sources and Download

tmuxp is available as open-source software under the MIT license.