I've switched my tech stacks several times in the past 10+ years. Something that has been consistently there throughout these times has been tmux. Here's how I'm using it with Rails + AI TUIs.

So what's tmux?

tmux is a terminal multiplexer. It lets you switch easily between several programs in one terminal, detach them (they keep running in the background) and reattach them to a different terminal.

I became aware of tmux around 2014 when I switched from Windows to Linux and I sshed into my servers and connections sometimes have been interrupted.

This is one thing tmux gracefully handles for you: when an shh connection is interrupted, and gets re-established, the tmux-session you started on the remote is still there so you can just attach to it and continue where you left of. Doing Linux updates via ssh this way is also less risky.

But there's more to it.

When starting tmux in your terminal, you notice it running by the sticky info bar at the bottom of your terminal:

If you didn't set up anything in your ~/tmux.conf, you can just use the terminal as is.

Sometimes, you might want to have multiple terminals beneath each other and you can do that easily using tmux: Hit <leader>+<shift>+2 and the tmux window will split horizontally:

If you need a vertical split, use <leader>+<shift>+5>.

These splits can be nested arbitrarily:

What's the <leader>?

If you're familiar with tools like nvim, you already know, what a <leader> is and the default for tmux is C-b which means CTRL+b.

So <leader>+<shift>+2 means "Hit CTRL+b, followed by <SHIFT+2>".

I've sticked with this default leader key for more than 10 years but after reading this great book about LazyVim (more specifically Chapter 2) last year and some pain in the wrist, I noticed that the root cause might be using the default tmux leader key.

Long story short: a few weeks ago, I changed my leader leader key to LEFT-ALT-M and this is much more comfortable to me. I can hit the LEFT-ALT key with my left thumb and the M key with my right index finger instead of stretching my left hand for <CTRL+b>.

Split panes are great but how do I navigate?

So with all these nested panes around, how do you select a particular one?

<leader>-q is here for the rescue. This will bring up an overlay with the numbers of the panes. Hitting this number rigth after <leader>-q, will focus that pane:

If you want to get rid of a pane, just exit that particular terminal.

You've got more?

Let's consider you're building a web application and there's some development tooling required:

• a web server
• one or more database(s) in Docker container(s)
• a editor, most likely nvim
• a shell to execute commands like bin/rails or bin/kamal
• one ore more AI agent TUIs, e.g. opencode
• a database TUI like sqlit
• a TUI to manage Docker like lazydocker

That's much more than you could fit into a few nested panes.

But tmux has got you covered: we can create new Windows inside tmux easily by hitting <leader>-c.

You can navigate them by using <leader>-<number-of-the-window>.

Having windows and panes at hand, you can now create and environment where your complete tooling is running side by side:

tmux app window

tmux layzvim window

tmux shell window

tmux opencode window

tmux sqlit window

The only downside: you have to re-create all of them after quitting the session.

If you keep running the session like forever, you can just detach from it using <leader>-d.

Using tmux ls you get a list of all running tmux sessions and you can attach to a running session using tmux attach -t <session-number>.

If you have multiple sessions running (I've almost 10 parallel tmux sessions running while writing this - in a tmux session, of course), identifying them by number, is not the easiest thing.

Hit <leader>-$ and give your session a memorable name.

Now you can also attach to it using tmux attach -t <session-name>.

Anyway, at some point you'll restart you machine and everything is gone...

Tmuxinator has entered the chat

That's where another tool comes handy: tmuxinator.

Tmuxinator helps you manage complex terminal sessions easily. Create, manage, and automate your dev environment with simple YAML configuration files today.

With tmuxinator you can persist your complex layouts in YAML files.

A YAML file for the session described above, could look like this:

name: name-of-session
root: path/to/the/project

windows:
  - dev:
      layout: even-vertical
      panes:
        - docker compose up -d
        - bin/dev
  - editor: nvim .
  - shell: bash
  - agent: opencode
  - sql: sqlit

This .tmuxinator.yml (notice the dot) file can be stored in multiple places: either in the root of your project or in the ~/.config/tmuxinator/ folder.

My workflow is to keep it inside the project and symlink it to the ~/.config/tmuxinator/ folder.

That way you can start a session from elsewhere globally using tmuxinator start <name-of-session>. If the session is already running, it will just attach to it.

If you enable bash completion for tmuxinator, you can just type tmuxinator start + <TAB> and it'll give you the list of defined sessions.

As tmuxinator is quite long to type, it is common, to alias it to mux (make sure to enable completion for this as well).

Speaking of running tmux session: you can easily hop between sessions using <leader>-s. This gives you a list of tmux sessions with a preview of it's windows and panes and you can just hit enter or the number of the session to switch to it:

With this at hand, you literally need just one instance of your Terminal.

And of course, you can always your mouse / trackpad if you enable it your tmux configuration.

Mine can be found here.

One more thing

tmux is comming to the Omarchy menu soon: