Zellij Upgrade for Claude Code SSH — Why I Switched from tmux

Why You Need a Terminal Multiplexer

Claude Code runs in the terminal. When you use it over SSH, a dropped connection kills the session — your conversation, the file being edited, the running build. All gone.

A terminal multiplexer (tmux, zellij) keeps the session alive as a server-side process. When SSH drops, the session keeps running. Reconnect, and you pick up exactly where you left off.

# Without multiplexer (SSH drops = game over)
Windows Terminal → SSH → Claude Code

# With zellij (session survives SSH drops)
Windows Terminal → SSH → zellij session → Claude Code

Installing Zellij

Downloading the binary directly is the simplest approach. No package manager dependencies — works the same on any Linux server.

# x86_64 Linux (v0.44.1)
curl -sL https://github.com/zellij-org/zellij/releases/download/v0.44.1/zellij-x86_64-unknown-linux-musl.tar.gz \
  | tar xz -C /usr/local/bin/

# Without sudo — install to user directory
mkdir -p ~/.local/bin
curl -sL https://github.com/zellij-org/zellij/releases/download/v0.44.1/zellij-x86_64-unknown-linux-musl.tar.gz \
  | tar xz -C ~/.local/bin/

Verify after install:

zellij --version
# zellij 0.44.1

Registering the z Shortcut

Typing zellij every time gets old. Add one alias to ~/.bashrc:

alias z="zellij"

Common commands become short:

z            # launch zellij
z ls         # list sessions
z a myses    # attach to session
z k myses    # kill session

zj Auto-Attach Script

This script attaches to an existing session or creates a new one. Run it after SSHing in, and you're immediately back in your working environment.

Save as ~/.local/bin/zj:

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

# Auto-detect zellij location
if command -v zellij &>/dev/null; then
    ZJ=zellij
elif [ -x "$HOME/.local/bin/zellij" ]; then
    ZJ="$HOME/.local/bin/zellij"
elif [ -x /usr/local/bin/zellij ]; then
    ZJ=/usr/local/bin/zellij
else
    echo "zellij not found"; exit 1
fi

LAYOUT_FILE="$HOME/.config/zellij/layouts/three.kdl"

cd "$DIR"

if $ZJ list-sessions 2>/dev/null | grep -q "$SESSION"; then
    $ZJ attach "$SESSION"
else
    if [ "$PANES" = "3" ] && [ -f "$LAYOUT_FILE" ]; then
        $ZJ -s "$SESSION" -n "$LAYOUT_FILE"
    else
        $ZJ -s "$SESSION"
    fi
fi

chmod +x ~/.local/bin/zj

Three-Pane Layout

Run Claude Code, watch build output, and do manual work — all in one view. Zellij layouts are defined in KDL format.

~/.config/zellij/layouts/three.kdl:

layout {
    pane split_direction="vertical" {
        pane
        pane
        pane
    }
}

One-Click Access with Windows bat Files

This bat file opens a new Windows Terminal tab, SSHes into the server, and attaches to the zellij session — all in one step. Make one per server and double-click to jump straight into any working environment.

@echo off
wt nt cmd /k ssh -t server-alias "/home/user/.local/bin/zj session-name ~/project-folder 3"

Practical example:

@echo off
wt nt cmd /k ssh -t myserver "/home/user/.local/bin/zj dev ~/project 3"

Known Bug: -s + --layout Combination

On zellij 0.44.1, combining a session name with a layout file behaves differently depending on the flag used.

# Broken — session created but layout not applied
zellij -s mysession --layout three

# Works — session name + layout applied together
zellij -s mysession -n three

SSH PATH Problem and Fix

When you run a command directly over SSH (ssh server "command"), a non-login shell opens. ~/.bashrc aliases and PATH additions don't apply, so zj and zellij show up as "command not found."

4 Reasons I Switched from tmux

Practical differences after switching from years of tmux usage.

Frequently Used Commands

CLI Commands

In-Session Shortcuts

Wrap-up