Tmux + Claude Code — Keep AI Working Even When SSH Drops

There is one problem you will inevitably hit when running Claude Code on a remote server over SSH. When the network drops, your Claude session dies with it.Close your laptop lid, lose Wi-Fi for a second, or accidentally close the Windows Terminal window — and everything you had in progress is gone. Re-launching resets the context from scratch. Adding tmux in between solves this entirely. The session lives on the server independent of the SSH connection, and when you reconnect you pick up exactly where you left off. This post shares the tmux configuration and automation scripts deployed across multiple production servers.

SSH Drop = Claude Session Gone

The traditional flow is straightforward.

Windows Terminal → SSH → claude → work

In this setup, the SSH connection is tightly coupled to the process lifecycle. The moment the SSH session drops, SIGHUP is sent to every process running inside it — including the claude process. Any in-progress file edits or analysis tasks are cut off mid-way.

The longer the task and the more servers you operate, the more often this happens. For tasks that require Claude to process multiple files in sequence — such as large-scale refactoring or code analysis — an interruption means starting over with fresh instructions.

How tmux Solves This

tmux is a terminal multiplexer. The core idea is simple: it decouples the terminal process from the SSH connection.

Windows Terminal → SSH → tmux session → Claude

A tmux session lives as a server process, not as a child of your SSH connection. When SSH drops, the tmux session remains on the server. Reconnect via SSH and run tmux attach — Claude is right there, exactly where you left it.

When to Use tmux vs. Not

tmux is not always necessary. Use it based on the nature of the task.

Separate aliases are used for each mode. c runs Claude Code immediately, cc is for reviewing conversation history.

alias c="command claude --dangerously-skip-permissions"
alias cc="claude-history"

Full .tmux.conf Configuration

Below is the full ~/.tmux.conf deployed across all servers. Every option has a reason. In particular, escape-time is covered in detail in the troubleshooting section below.

set -g default-terminal "xterm-256color"
set -sg escape-time 50
set -g history-limit 100000
set -g set-clipboard on
set -g allow-passthrough off
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
set -g mouse on
set -g status-left '[#S] '
set -g status-right '%H:%M %Y-%m-%d'
set -g status-style 'bg=colour235,fg=colour250'
setw -g monitor-activity on
set -g visual-activity off

tmux-claude Automation Script

Manually creating a session, launching Claude, and splitting panes every time is tedious. Place the script below at /usr/local/bin/tmux-claudeto get your full environment with a single command. The path /usr/local/bin/ is chosen because it is on the system PATH and available even when .bashrc is not sourced during SSH non-interactive execution. (See troubleshooting below.)

#!/bin/bash
SESSION="${1:-ai}"
DIR="${2:-~/ai}"
PANES="${3:-1}"

if tmux has-session -t "$SESSION" 2>/dev/null; then
    tmux attach -t "$SESSION"
else
    tmux new -s "$SESSION" -d -c "$DIR"
    tmux send-keys -t "$SESSION" 'c' Enter
    for ((i=2; i<=PANES; i++)); do
        tmux split-window -h -t "$SESSION" -c "$DIR"
        tmux send-keys -t "$SESSION" 'c' Enter
        tmux select-layout -t "$SESSION" even-horizontal
    done
    tmux attach -t "$SESSION"
fi

Usage examples

# Default (session name: ai, working dir: ~/ai, 1 pane)
tmux-claude

# Custom session name and directory
tmux-claude dev ~/project

# 3-pane split (3 Claude instances simultaneously)
tmux-claude ai ~/ai 3

One-Click Launch from Windows

A batch file in Windows Terminal can handle SSH connection + tmux session entry in one step. Create a bat file per server and double-clicking the icon opens the Claude environment instantly.

Single pane

@echo off
wt nt cmd /k ssh -t main-server "tmux-claude ai ~/ai"

3-pane split (3 Claude instances)

@echo off
wt nt cmd /k ssh -t main-server "tmux-claude ai ~/ai 3"

Essential Commands Reference

Session management

Inside a session (press Ctrl+b, release, then the key)

Troubleshooting Notes

Issues encountered during setup are documented here. Most are combination-specific problems that are not easily found by searching, so the root cause can take time to identify.

1. OSC color code strings printed to terminal

Approaches that failed

# Attempt 1: screen-256color + terminal-overrides Tc → failed
set -g default-terminal "screen-256color"

# Attempt 2: tmux-256color + removing focus-events → failed
set -g default-terminal "tmux-256color"

# Attempt 3: removing all terminal-overrides → failed

Final fix

set -g default-terminal "xterm-256color"
set -sg escape-time 50        # critical: must not be 0
set -g allow-passthrough off  # block passthrough

2. Claude Code install script: sh vs. bash

# This fails
curl -fsSL https://claude.ai/install.sh | sh

# Must specify bash explicitly
curl -fsSL https://claude.ai/install.sh | bash

3. Command not found in SSH non-interactive mode

4. Changes to tmux.conf have no effect

5. Old Claude version running after native install

6. Session names with special characters

Mass Deployment to Multiple Servers

When managing many servers, connecting to each one individually to configure tmux is inefficient. Using scp and ssh inside a loop with background parallel execution completes the full deployment in seconds.

Deploy .tmux.conf

for server in server1 server2 server3; do
  scp -q ~/.tmux.conf ${server}:~/.tmux.conf &
done
wait

Deploy tmux-claude script

for server in server1 server2 server3; do
  scp -q /usr/local/bin/tmux-claude ${server}:/tmp/tmux-claude
  ssh ${server} "sudo cp /tmp/tmux-claude /usr/local/bin/tmux-claude && sudo chmod +x /usr/local/bin/tmux-claude" &
done
wait

Wrap-up

The tmux + Claude Code combination is simple to set up and immediately effective. You can hand off long tasks without worrying about SSH drops, and running multiple Claude instances in parallel panes for independent tasks is straightforward.

The most important configuration detail is escape-time. Many guides suggest setting it to 0 for responsiveness, but combining that with Windows Terminal causes OSC response strings to appear as raw text in the terminal. 50ms is the right value.

The biggest change tmux brought is the absence of urgency — there is no pressure to finish right now. When it is time to step away, Ctrl+b → d gets you out. When you return, Claude is waiting in the same place.