Tmux Setup

Why Tmux?

Tmux gives every agent a permanent, addressable pane. When an agent finishes, back2vibing restores focus to that exact pane — the right session, the right window, the right pane. No hunting through tabs.

Persistent sessions

Your agents keep running even if your terminal window closes or your SSH connection drops. Reconnect and everything is exactly where you left it.

Automatic focus restoration

Back2vibing tracks which tmux pane each agent runs in. When an agent finishes, focus snaps to that pane automatically.

Parallel agents

Split panes let you run multiple agents side by side. Switch between project sessions instantly.

Zero overhead at scale

One agent is manageable without tmux. Three agents across two projects is chaos — unless your tools handle the routing.

Quick Start: The Dotfiles Way

The fastest way to set up tmux for back2vibing is to use our recommended dotfiles. This will automatically install tmux, sesh, and all necessary configurations for macOS or Linux.

# Clone and run the interactive setup
git clone https://github.com/builtby-win/dotfiles.git ~/dotfiles
cd ~/dotfiles
./setup.sh

The setup script will walk you through installing everything you need, including terminal themes and shell integrations.

Targeted Install

If you only want the tmux configurations without a full system setup, you can run:

pnpm setup  # Installs tmux and sesh configs via stow
# OR use our alias if already installed
bb tmux

Ergonomics: The j+k Leader

Standard tmux uses Ctrl+b as the prefix (the “Leader”), which can be hard on the hands over time. Our dotfiles include a Karabiner-Elements configuration that maps holding j + k together to the Leader key.

• Standard: Ctrl+b + key
• Ergonomic: Hold j and k simultaneously, then press key

This allows you to trigger any tmux command without ever leaving the home row.

---

Manual Installation (Optional)

If you prefer to manage your own config, follow these steps.

Prerequisites

• macOS or Linux
• Homebrew (macOS) or equivalent package manager
• A terminal emulator (Ghostty recommended)

Step 1: Install tmux and sesh

brew install tmux sesh

Step 2: Install back2vibing tmux config

git clone https://github.com/builtby-win/dotfiles.git ~/dotfiles
cd ~/dotfiles
stow -d stow-packages -t ~ tmux

This uses GNU Stow to symlink the config files into your home directory. Stow will warn you if there is a conflict — your existing files will not be overwritten.

Already have a tmux config?

You can skip the dotfiles and add back2vibing’s tmux integration manually. Back2vibing will automatically create its config at ~/Library/Application Support/back2vibing/tmux/back2vibing-tmux.conf. Source it from your existing .tmux.conf:

if-shell '[ -f "$HOME/Library/Application Support/back2vibing/tmux/back2vibing-tmux.conf" ]' \
  'source-file "$HOME/Library/Application Support/back2vibing/tmux/back2vibing-tmux.conf"'

Step 3: Install tmux plugins

1. Install TPM (Tmux Plugin Manager):

   git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

2. Start tmux:

   tmux

3. Press Leader then I (capital I) to install all plugins.

4. Wait for the “Done” message at the bottom of the screen.

Step 4: Set up the shell hook

Add the back2vibing shell hook to your shell config so b2v can track sessions:

# Add to ~/.zshrc (or ~/.bashrc for bash)
eval "$(b2v shell-hook --shell zsh)"

Then restart your shell or reload:

source ~/.zshrc

5 Keybindings You Need

These are the essential keybindings from our recommended config. All use Ctrl+b (or j+k) as the prefix (called “Leader”).

Shortcut	What it does	When to use it
Leader Space	Open session picker	Switch between projects
Leader /	Command palette	Forgot a keybinding? Search here
Leader d	Split pane vertically	Run an agent side-by-side
Leader g	Floating terminal	Quick command without leaving your pane
Leader T	Jump to last session	Bounce between two projects

Note

Press Leader / inside tmux to search all available keybindings. The command palette is your cheat sheet — you do not need to memorize anything else.

Verify It Works

1. Open tmux: tmux
2. Split a pane: Leader d
3. Start an agent in one pane: b2v claude
4. Switch to the other pane: Leader h or Leader l
5. When the agent finishes, your focus should snap back to the agent’s pane.

If focus snaps back, you are all set.

Session Picker Deep Dive

The session picker (Leader Space) is powered by sesh and fzf. It has several modes:

Key	Mode	What it shows
j / k	Navigate	Move up and down the list
/	Search	Enable fuzzy search
Ctrl+A	All sessions	Reload the full list
Ctrl+T	Tmux only	Show only tmux sessions
Ctrl+G	Configs	Show config directories
Ctrl+X	Zoxide	Show recently visited directories
x	Kill	Delete a session

The right panel shows a live preview of the selected session’s windows and panes.

Plugins Included

Our dotfiles config installs these plugins via TPM:

Plugin	What it does
tmux-resurrect	Save and restore sessions across restarts
tmux-continuum	Auto-save sessions in the background
tmux-fingers	Copy text with keyboard hints (Leader f)
tmux-yank	Enhanced clipboard integration
tmux-floax	Floating terminal overlay (Leader g)
tmux-fzf-url	Open URLs from the pane with fzf (Leader u)

Next Steps

Sessions Manage active and completed agents from one control panel.

CLI Run agents from the terminal with tmux monitoring.

SSH Remote Use tmux with back2vibing on remote machines.