---
title: Templating tmux with tmuxinator
teaser: 'tmux does one thing and does it well as any unix tool should, but that doesn''t
  mean you should stop there.

  '
tags: tmux,cli,unix
author: Simon van Dyk
published_on: 2019-03-13
---

If you've never used tmux before, [get a crash
course](https://thoughtbot.com/blog/a-tmux-crash-course) before reading further.

[tmuxinator](https://github.com/tmuxinator/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

```shell
$ 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.

<kbd>tmuxinator new space-kitties</kbd>

This opens the new project config in your default editor.

```yaml
# /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.

```yaml
# /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:

<kbd>tmuxinator start space-kitties</kbd>

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`.

```shell
$ 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:

<kbd>tmuxinator edit space-kitties</kbd>

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

```yaml
# ...

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!

<kbd>tmuxinator start space-kitties</kbd>

<img
src="https://images.thoughtbot.com/svd-turbocharge-tmux-with-tmuxinator/ZlkraL7ZSGOfAFdSzHIY_tmuxinator-screenshot-min.png"
alt="terminal running tmux" style="box-shadow: 0px 18px 23px rgba(0,0,0,0.1)" />

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:

```shell
alias tx=tmuxinator
```

Happy templating! 🎉