Using iTerm2’s built-in integration with tmux

Have you ever had a dozen terminal windows open to a remote system you are working on only to be suddenly disconnected and have to start completely over? Or been so wrapped up in a project across multiple windows and hosts that you stayed at work way later than you were supposed to just so you wouldn’t lose your place and have to start over in the morning? By using a combination of iTerm2 and tmux, you can regain control of your workflow, lose your fear of the disconnect, and be much more productive.

iTerm2 is a very capable terminal application for MacOS. One of its best but probably least-used features is its native integration with tmux. Tmux is a terminal multiplexer. Simply put, this allows you to split one terminal session into many. This can be done by using different windows/tabs or splitting the screen vertically and horizontally multiple times until you have your ideal layout. But using tmux you can also disconnect and leave your sessions in tact, ready for you when you return, from another IP or even another computer.

Tmux can be a little daunting, but there’s a great introduction to it available here:

Manually, you could ssh into a remote host, then start tmux

Once tmux is started you get a fresh terminal in the same window, but now there is a green bar across the bottom.

Now, tmux is a very powerful tool, but it can have a rather steep learning curve. It also requires a number of keystrokes/interactions for simple tasks.

For instance, a screen can be divided vertically using cmd+b and then “%”. The first key combination (ctrl+b) puts tmux into command mode. The percent tells tmux to split the window vertically.

Even moving between the vertical panes takes two keyboard interactions. The first is ctrl+b which puts tmux into command mode. The second is an arrow key to then toggle between the two terminals.

Overall not a very mac-like experience.

Thats where the native integration in iTerm2 comes in. After initially logging in to the remote system, instead of running tmux alone, use the command “tmux -CC”.

This results in a new window appearing:

Now this window is not a normal terminal window, even if it looks like one. It is a tmux window. To demonstrate why this is important, lets customize the window, adding some panes and running some commands

To divide the window into two vertical panes, right-click in the window and select “Split Pane Vertically”

You can continue to divide panes by repeating the processes and splitting vertically and horizontally.

You an also resize each pane by grabbing the dividers and of course you can resize the whole window as well.

This is a far more mac-like experience. You can click between panes, tabs and windows, resize with a mouse, use menus to open and close new panes, etc.

Pro Tip: Notice that the current active pane is darker and the others are grayed-out. This is a setting in iTerm2 and is usually even more noticeable but I prefer it to be fairly subtle. To adjust this effect, go to the iTerm2 menu, click “Preferences…” and go to the “Appearance” tab. Change the value of the “Dimming amount” slider to match your liking.

Ok, now that you have your window set up the way you like, and you’ve been working and productive for a while, what happens it you lose your connection, or its time to go home for the day?

The most compelling reason to use tmux is for just these situations. There are two modes of separation for tmux: detach and kill. Detach is what happens by default when you lose connectivity, but you can also manually detach from your session as well. Kill is exactly what it sounds like, and will kill your session and you can start over on your next login.

For now, if we close our iTerm2 window, we should see this dialog:

For now, choose detach.

Now we can log out of our terminal session, even close iTerm2, restart the computer, go home and connect from a different IP, and none of this matters to your session that is still in progress.

When you are ready to reconnect, simply launch iTerm2, and ssh back into the server you were on. Then type “tmux -CC attach”

When you press enter, your previous session will be restored and your customized window will reappear, with all your processes still running like you never left.

Ok, so what if want to automate the whole login experience, and create a tmux session if one does not exist, and attach to one if it does? For this we need to create a new profile.

Head to the iTerm2 menu, select “Preferences…” and switch to “Profiles”. Create a new profile, name it, change the “Command” radio button from “Login Shell” to “Command”. Change the command to:

ssh -t <yourusername>@<yourserver> “tmux -CC attach || tmux -CC”

Now, in iTerm2, go to the “Profiles” menu at the top of the screen, and select your new profile.

Your existing tmux session will appear, or if you have no session running, a new one will be created.

There is much, much more power in the tmux/iTerm2 combination including the tmux rc files where you can configure your tmux sessions uniquely to your specifications. But this is a good start. You should never worry about being suddenly disconnected or being able to pick up where you left off between physical locations again.

CEO of NovCon Solutions LLC. Cat herder, pentester, Information Security professional, technology and shiny stuff enthusiast.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store