Auto-tmux for SSH logins

bashrc-tmux automatically puts interactive SSH logins into a persistent tmux workspace. If the connection drops or a client detaches, programs and windows keep running in an anchor session and are available on the next login.

The maintained wrapper supports Bash and zsh and requires tmux 3.2a or newer. It does nothing for local shells, noninteractive shells, sessions without a terminal, nested tmux clients, or hosts where tmux is unavailable.

Setup

Source the wrapper from the startup file for your login shell.

For Bash, add this to ~/.bashrc:

source /path/to/bashrc-tmux/bashrc-tmux

For zsh, add the same line to ~/.zshrc:

source /path/to/bashrc-tmux/bashrc-tmux

The wrapper performs its own interactive-shell check, so an external $PS1 test is neither required nor recommended.

Powerlevel10k instant prompt

When using Powerlevel10k's instant prompt, source bashrc-tmux before the instant-prompt block near the top of ~/.zshrc. Entering tmux may interact with the terminal and therefore must happen before the cached prompt is loaded:

source /path/to/bashrc-tmux/bashrc-tmux

# Enable Powerlevel10k instant prompt. Should stay close to the top of .zshrc.
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
  source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi

Behavior

For a qualifying SSH login, the wrapper creates or reuses an anchor named ssh-$USER. Each connection gets an automatically named session linked to that anchor. Linked sessions share windows and programs, while each client can select its own current window and active pane.

Detach normally with tmux's standard C-b d. The per-login linked session is then destroyed and the outer SSH shell exits, but the anchor and its windows remain. Logging in again creates a fresh linked session for the same workspace. Network loss and client termination have the same cleanup behavior.

If tmux cannot create or start a session, the wrapper prints a short diagnostic and leaves you at the ordinary SSH shell instead of closing the connection.

Controls

Set BASHRC_TMUX_DISABLE to any nonempty value to skip auto-tmux for that shell. This is the recovery path if tmux or its configuration is broken:

BASHRC_TMUX_DISABLE=1 zsh -il

Set BASHRC_TMUX_IGNORE_SIZE to any nonempty value to add tmux's ignore-size client flag. This prevents that client from affecting the size chosen for other clients:

BASHRC_TMUX_IGNORE_SIZE=1 ssh host

Multiple remote tmux workspaces

Set BASHRC_TMUX_SESSION to add an isolated suffix to the anchor name:

ssh -t host BASHRC_TMUX_SESSION=project zsh -il

This example uses ssh-$USER-project. A suffix must be nonempty and contain only ASCII letters, digits, _, or -. Invalid values produce a warning and skip auto-tmux; they never fall back to a different shared session.

Legacy Xpra helper

bashrc-xpra is retained for historical users, but it is legacy and unsupported. It has not been modernized, should not be newly activated, and requires a suitable system-supported Xpra installation. Modernizing it is a separate project.

For an existing deployment, current Xpra clients use the URI form:

xpra attach ssh://remote-system/100

Development

Run the maintained checks with:

make check

The test harness exercises Bash and zsh through pseudo-terminals using a fake tmux. bashrc-tmux is syntax-checked and checked with ShellCheck. bashrc-xpra is syntax-checked only and is intentionally outside the maintained lint contract.