Adventures in Tmux, Tmuxinator, and Powerline

Fiddling with terminals

After a few conversations with coworker, I found myself seeing possible uses for tmux in my workflows - in particular for working on Hugo. That led to thoughts of scripting tmux with tmuxinator and making it pretty with Powerline.

iTerm2 Splits or tmux Panes

Before those conversations led to ~6 hours of late-night exploration, I had been using iTerm2 splits happily. Each time I needed to restart my terminals though, I needed to subdivide my windows again. My workflow often consists of two exploration terminals (top left and top right), one Hugo server session (bottom left), and one terminal for writing a post on what I was exploring (botom right).

The effort of splitting the window was ameliorated by learning the shortcut keys to doing so. But the need to navigate each of the splits to a specfic directory and always kick off the hugo server -D in one of them made me think automatically doing so each time that I wanted to work on this project would be handy.

And when I stumbled on references to the text triumvirate I was lured in by the eye candy - not just for tmux but vim as well.

Instaling tmux, tmuxinator, and Powerline

The installation of the tools I needed wasn’t too bad.

> brew install tmux
> gem install tmuxinator

Wait, I Don’t Need to Install Powerline for tmux?!

As it turns out, in order to get some of the pretty statuslines in tmux you only need a Powerline-patched font and some .tmux.conf changes. No need to install the Python extension unless you also want vim to have a pretty statusline too. More time that night than I would like to admit was spent trying to navigate the Byzantine instructions - with all their seemingly conflicting “note” sections - of installing with pip and then configuring in various files.

You do need to install Powerline with pip using the following command (due to PyPI naming conflicts):

> pip install powerline-status

And for vim to use Powerline for the statusline I needed this in my .vimrc:

set rtp+=/Library/Python/2.7/site-packages/powerline/bindings/vim/
set laststatus=2

I already had a Powerline font installed based on previous conversations with this coworker which led to the land of zsh and oh my zsh. (Yes, I know some prefer alternatives like Prezto and even the creator has admitted it’s big. Even so, I’m happy with it for the time being.) The one I chose to install based on recommendation was Menlo LG M DZ Regular for Powerline.

Things You Don’t Need (YMMV)

Before that, after reading the documentation I had tried lines like the following in my .vimrc:

python from powerline.vim import setup as powerline_setup
python powerline_setup()
python del powerline_setup
:let g:powerline_pycmd = 'py'
:let g:powerline_pyeval = 'py'

And these lines in my .tmux.conf:

run-shell "powerline-daemon -q"
source "/Library/Python/2.7/site-packages/powerline/bindings/tmux/powerline.conf"

And these lines in my .zshrc:

POWERLINE_CONFIG_COMMAND="python /Library/Python/2.7/site-packages/powerline/"

None of these turned out to help and all were eventually removed despite what the documentation said.

Basic tmuxinator Configuration

One thing you will want to do for sure is verify that you are setting the $EDITOR in your shell. Do this by running the following command:

> echo $EDITOR

If that results in a blank line you will need to add the following to your shelly configuration (example for zsh as the shell and vim as the editor):

export EDITOR='vim'


In order to get autocompletion, you need to grab the appropriate completion script for your shell of choice and install it in ~/.bin/. For me, I’m using zsh so I ended up with ~/.bin/tmuxinator.zsh.

For tmuxinator to benefit, I needed this line in .zshrc:

source ~/.bin/tmuxinator.zsh

Creating and Configuring tmuxinator Projects

At this point, I was able to follow the “Usage” section of the tmuxinator README to get what I needed for my four window setup described earlier.

Configuring tmux

I also spent considerable time pulling together my .tmux.conf. When tmux failed to start when called via tmuxinator (or more likely the shorter mux) I would get some really unhelpful messages saying there was nothing listening on the default.

no server running on /tmp/tmux-0/default

Mac Issues

As is called out in this post you will probably run into issues installing tmux via homebrew when it comes to actually running it.

The solution seems to be installing another package, reattach-to-user-namespace, with:

> brew install reattach-to-user-namespace

And adding the following line to your .tmux.conf:

set -g default-command "reattach-to-user-namespace -l zsh

Helpful Resources and Challenges

Thankfully there are many good sources available if you look. I linked to a number of them at the top of my .tmux.conf.

One thing to be aware of is that you will find not all of the advice out there will work for you. At the time of this writing, I’m still working through how to get copy/paste to work as I would like in vim inside a tmux session and that is represented in some of the commented out lines in the file. I’m sure some of this is my lack of familiarity with the interactions between vim, tmux, and iTerm2.