Templating tmux with tmuxinator

If you’ve never used tmux before, get a crash course before reading further.

tmuxinator is a ruby gem that allows you to easily manage tmux sessions by using yaml files to describe the layout of a tmux session, and open up that session with a single command.

Getting started

Install tmuxinator

$ gem install tmuxinator

# OR via homebrew

$ brew tap nexeck/homebrew-tmuxinator
$ brew install nexeck/homebrew-tmuxinator/tmuxinator

Create a tmux session template, tmuxinator calls these projects.

tmuxinator new space-kitties

This opens the new project config in your default editor.

# /Users/simon/.config/tmuxinator/space-kitties.yml

name: space-kitties
root: ~/

# ... more config here

windows:
  - editor:
      layout: main-vertical
      # Synchronize all panes of this window, can be enabled before or after the pane commands run.
      # 'before' represents legacy functionality and will be deprecated in a future release, in favour of 'after'
      # synchronize: after
      panes:
        - vim
        - guard
  - server: bundle exec rails s
  - logs: tail -f log/development.log

The config has helpful comments and hooks to run before and after creating the session and is a good starting point. Let’s edit it a little.

# /Users/simon/.config/tmuxinator/space-kitties.yml

name: space-kitties
root: ~/Code/space-kitties

# start session with this window open
startup_window: editor

windows:
  - server: heroku local -p 3000
  - editor:
      layout: main-vertical
      panes:
          - vim
          - bundle exec rails t test/*

We’ve simplified this and specified two windows. One for a server and the other for our editor. The editor window will have two panes, one for vim and the other for running tests.

We also want to be on the editor window when we fire it up, so we declare that our startup_window will be the editor.

Save the file and in your terminal run:

tmuxinator start space-kitties

It should have fired up your tmux session template 💰.

Custom layouts

I have found I often need a slightly different layout than the defaults available in tmux: even-horizontal, even-vertical, main-horizontal, main-vertical, or tiled.

This happens to me while I’m in a project, and I want to replicate my current tmux session’s layout the next time I open this project with tmuxinator. To do this, while you’re in your tmux session with the layout you want, run tmux list-windows.

$ tmux list-windows
1: server- (1 panes) [255x64] [layout c25d,255x64,0,0,0] @0
2: editor* (2 panes) [255x64] [layout 968b,255x64,0,0{172x64,0,0,1,82x64,173,0,3}] @1 (active)

This shows me I have two windows named server and editor, and the editor window has two panes. It also prints the layout of each window. You can literally copy this into the tmuxinator config file for your project.

To do this run:

tmuxinator edit space-kitties

Then change the value of the layout for the window you want to change:

# ...

windows:
  - server: heroku local -p 3000
  - editor:
      layout: 968b,255x64,0,0{172x64,0,0,1,82x64,173,0,3}
      panes:
          - vim
          - bundle exec rails t test/*

Give it a go!

tmuxinator start space-kitties

It’s easy to get excited and add too much to your config 🤩. Here be dragons. Rather use tmuxinator as a basic starting point to make your workflow more comfortable. Remember if you make something easier, you’re more likely to do it.

Lastly, tmuxinator is an awful long command to run, try aliasing it to something shorter in your shell config:

alias tx=tmuxinator

Happy templating! 🎉