Tmuxifier: Tmux sessions described as shell scripts

The problem: a Tmux setup you rebuild by hand every morning

Most people who use Tmux end up with a working arrangement they assembled by muscle memory. Three splits in a specific ratio, one window titled for the server, a second window for logs, a particular pane selected on arrival. Rebuilding that arrangement by hand every session is tedious, and documenting it in a wiki or a note tends to go stale, because the arrangement only exists in the muscle memory that created it.

Tmuxifier addresses exactly that gap. It provides a way to create, edit, manage and load layout files, which are shell scripts that use the tmux command together with helper commands the tool provides for managing sessions and windows. The result is a text file that can live in a dotfiles repository, be reviewed in a diff, and be replayed on another machine.

The audience is therefore Tmux users who already have a workflow worth preserving, not people looking for a terminal multiplexer. If you do not use Tmux, nothing here applies. If you use Tmux but never build elaborate layouts, the setup cost of a shell script layout file and a PATH entry is probably more than the problem you are solving.

There is one more reason to care, and it is the subject of this project rather than of its competitor. Because a layout is a shell script, the same file can do things a static declaration cannot, such as running a command inside a pane at creation time.

Window layouts split panes by percentage, not by name

The unit of work is a window layout. Creating one gives you a new Tmux window, optionally with a title and a root path that every shell in the window changes directory into. The interesting part is the split control, which works in percentages rather than by counting panes.

A layout file for a window looks like this:

window_root "~/Desktop"
new_window "Example Window"
split_v 20
run_cmd "watch -t date"
split_h 60
select_pane 0

The helper commands are readable as they are. window_root sets the directory for the window, new_window names it, split_v and split_h split vertically and horizontally using the given percentage, run_cmd runs a command, and select_pane picks which pane is active.

Once the file exists, you can load it into the session you are already in:

tmuxifier load-window example

The same window layout can also be pulled into a session layout, in which case the window is created along with the session. That is the layering that makes the tool useful: a window layout is a reusable building block, and a session layout is an ordered set of blocks.

Session layouts are shell scripts too, and that cuts both ways

A session layout creates a new Tmux session, optionally with a title and a root path for all shells in it. Windows enter a session layout in one of two ways, either by loading an existing window layout or by being defined inline in the session file. The naming convention is a fixed suffix, a window layout file ends in .window.sh and a session layout file ends in .session.sh.

The core difference from the project it was inspired by is the file format. Tmuxinator, which the project names as its main inspiration, uses YAML files to describe sessions. Tmuxifier uses shell scripts instead. The stated benefit is total control over Tmux, and the stated cost is that the definition files are more complicated to work with. Both halves of that trade are real, and the second half is the one you notice when you open someone else's layout.

The second difference is conceptual. Tmuxifier drops the project idea and speaks in terms of sessions and windows, matching how Tmux itself is organised. A session layout pulls in windows by name with a load_window call, so a session file reads as a manifest of reusable windows rather than a monolithic description.

The result is a tool with a wide ceiling and a steep first hour. That combination suits people who already know exactly what they want their Tmux to look like.

Getting it on PATH, and the shell init line that matters

The manual install is a clone into your home directory, and the bin folder has to end up on your PATH:

git clone https://github.com/jimeh/tmuxifier.git ~/.tmuxifier

export PATH="$HOME/.tmuxifier/bin:$PATH"

The equivalent line for tcsh and for fish is documented separately, and the fish variant uses the fish syntax for extending a global PATH variable. A custom install path is supported: clone wherever you like and add that bin directory to your PATH instead.

There is also a TPM route for people who already manage Tmux plugins that way. The plugin declaration is a single line, and TPM installs the repository into its plugin directory, which by default is $HOME/.tmux/plugins, after which the bin directory for the plugin needs to be on your PATH:

set -g @plugin 'jimeh/tmuxifier'

The second part of setup is a line in your shell profile, and this is the step that surprises people. In bash and zsh you add the following to your ~/.profile, ~/.bash_profile, ~/.zshrc or an equivalent file:

eval "$(tmuxifier init -)"

The tcsh form uses backticks instead of the double quotes, and the fish form passes fish as an argument, eval (tmuxifier init - fish), which fits that shell's command substitution rules. The init scripts live in the repository as init.sh, init.tcsh and init.fish, and the top level tmuxifier.tmux file is the plugin entry point.

The eval line is what installs the shell completion. The tool ships completion for bash, zsh, tcsh and fish, and if that gets in the way you can turn it off by setting the TMUXIFIER_NO_COMPLETE environment variable to 1. Completion is also the reason the init step is not optional in practice, since without it you lose tab completion for the helper commands.

Your first layout, from an empty directory to a loaded window

No layouts ship with the tool, which is the one thing a new user has to accept before anything else. The way out is to let the tool generate a starter file.

tmuxifier new-window my-awesome-window

That creates a file named my-awesome-window.window.sh inside the directory named by $TMUXIFIER_LAYOUT_PATH, and opens it in whichever editor $EDITOR points at. The generated file is pre-populated with examples and comments explaining what each helper does, so the file teaches you its own format.

After you edit and save it, loading it is the same command shape you saw in the README example:

tmuxifier load-window my-awesome-window

The window appears in your current session with the splits, titles and commands your file describes. If the layout is wrong, you edit the file and load it again, which is the loop that makes the format worth having.

Session layouts follow the same pattern with a different suffix and different pre-populated content:

tmuxifier new-session my-awesome-session
tmuxifier load-session my-awesome-session

To include a window you already defined in that session file, add a load_window line for it. A full reference of the available commands and their aliases is available from the tool itself, tmuxifier help.

Where Tmuxifier stops being the right tool

The limitations follow directly from the design, and they are not small ones.

First, a layout file is shell code, so loading a layout executes it. That is what buys the flexibility, and it is also the risk: a layout fetched from somewhere you do not trust is a script, not data. The team format, where a layout is shared among several people, has exactly this exposure.

Second, the format is harder to read than YAML, as the project itself acknowledges. There is no schema, no validation step described, and no command that prints the resolved structure of a layout before running it. When a layout misbehaves, you debug shell output rather than a diff of a declarative file.

Third, the documentation is thin in a visible place. The usage section in the README carries a note that the section needs expanding, and the help output is the only complete command list. If you want to know every helper command and its flags, the source in the lib and libexec directories is the documentation.

Fourth, this is a shell tool with shell dependencies. It assumes Bash, zsh, tcsh or fish, it assumes a working Tmux, and it assumes you are comfortable editing shell files by hand. The Makefile shows the test harness is a downloaded shell test runner with assert and stub helpers fetched over the network, so running the test suite is not a self-contained operation.

Tmuxifier against Tmuxinator, and the update path

The project names Tmuxinator as its inspiration and states the differences plainly. Tmuxinator defines sessions and windows in YAML, Tmuxifier defines them in shell scripts. Tmuxifier drops the project concept in favour of sessions and windows, which lets a session layout load a whole session's worth of windows by reference. The project also notes that its shell script structure and shell completion setup came from the internals of rbenv, which explains the init and completion design as much as the format does.

If YAML is what your team reads comfortably, the difference in format is the whole argument, and it is not close. If you want maximum control over Tmux calls, the script format is the point, and the same comparison cuts the other way. Tmuxifier itself ships no layouts; you write your own.

Updating is a pull. The instructions are to change into the directory where you cloned the tool and run git pull, and the clone is expected to live at ~/.tmuxifier unless you chose a custom path.

cd ~/.tmuxifier
git pull

The licence is MIT, which is permissive and imposes no obligations on users beyond keeping the notice. The repository is not archived and the last push was on 2026-10-18, so the code is receiving changes, but there are no GitHub releases, so there is no version to pin and no changelog to read before you pull. Updating is therefore a blind operation on a tool that runs shell code on your machine, and the practical habit is to read the diff before pulling rather than after.

Editorial conclusion

Adopt Tmuxifier if you keep rebuilding the same multi-pane Tmux setup and want that setup stored as reviewable text in your own dotfiles repository. Do not adopt it if you want a declarative format a non-shell reader can grasp, or if you expect layouts to be included, since none ship with it. Before you rely on it, create one window layout with tmuxifier new-window, load it with tmuxifier load-window, and confirm the pane splits land where you expect, since the layout file is ordinary shell code that runs as written.

Frequently asked questions

Official sources

1. Issues
2. jimeh/tmuxifier on GitHub
3. License: MIT
4. README