How to Run Claude Code with tmux on a VPS

TL;DR

Start every Claude Code session with tmux new -s claude-<task>, run your agent inside it, and detach with Ctrl+b d. The session keeps running after you close SSH. Reconnect with tmux attach -t claude-<task>. Use tmux windows (Ctrl+b c) to run multiple agents side by side without opening multiple SSH connections. If you want session persistence without the terminal management overhead, Grass provides always-on cloud VMs where agent sessions survive disconnects automatically.

Prerequisites

• A VPS running any systemd-based Linux distro (Ubuntu 22.04+, Debian 12+, etc.)
• SSH access with a non-root user
• Claude Code, Codex CLI, Aider, or OpenCode installed on the server
• tmux ≥ 2.6 (any version in default repos since 2018 qualifies)

If you need to understand why your agent dies when SSH disconnects before setting up tmux, see Keep Claude Code Running After SSH Disconnects first. This guide assumes you've made that decision and focuses on working with tmux day-to-day.

Step 1 — Install tmux

sudo apt update && sudo apt install -y tmux

Verify:

tmux -V
# tmux 3.3a

Any version ≥ 2.6 works for everything in this guide.

How do you start a Claude Code session in tmux?

Always name sessions after the task, not generic names. When you have three agents running, session1, session2, session3 tells you nothing.

tmux new -s claude-auth-refactor

You're now inside tmux. The status bar at the bottom shows the session name. Start the agent:

claude -p "Refactor the auth module to use the new JWT library. Run tests after each file."

The agent is now running inside tmux. It will keep running when you detach.

How do you leave a session without stopping the agent?

Detach:

Ctrl+b d

You're back at your server's regular shell. The tmux session and everything inside it is still running. You can close your SSH connection, close your laptop, or switch networks — the agent continues.

How do you reconnect to a running session?

SSH back in, then:

tmux attach -t claude-auth-refactor

You're back in the session exactly as you left it — the agent output, the scroll history, everything.

To see all running sessions first:

tmux ls
# claude-auth-refactor: 1 windows (created Mon May 12 08:14:02 2026) (attached)
# claude-api-migration: 1 windows (created Mon May 12 09:45:31 2026)

If you only have one session, tmux attach without a name works.

How do you run multiple agents without multiple SSH connections?

Two patterns. Use whichever matches how you think about your work.

Separate sessions

One tmux new -s <name> per agent. Each session is independent — detach from one, attach to another.

# Start backend agent
tmux new -s claude-backend
# start agent, Ctrl+b d

# Start frontend agent
tmux new -s claude-frontend
# start agent, Ctrl+b d

# Check on backend later
tmux attach -t claude-backend
# Ctrl+b d to leave again

This is the cleanest model for parallel agents on separate tasks. You're never confused about which agent is which.

Multiple windows in one session

One session, multiple windows. Switch between agents with a keystroke — no re-attaching needed.

tmux new -s agents
# window 0 opens automatically — start first agent

Ctrl+b c        # open window 1
# start second agent

Ctrl+b c        # open window 2
# start third agent

Switch between windows:

Ctrl+b 0    # window 0
Ctrl+b 1    # window 1
Ctrl+b n    # next window
Ctrl+b p    # previous window

Rename a window so you know what's in it:

Ctrl+b ,
# type new name, Enter

The status bar shows all windows and highlights the active one.

What tmux commands actually matter for agent workflows?

Scrolling (Ctrl+b [) is the one that catches people. When an agent has run for an hour and you want to see earlier output, you need copy mode. Press Ctrl+b [ to enter it, scroll with arrow keys or PageUp/PageDown, and press q to exit.

What tmux config should you set for agent work?

Create ~/.tmux.conf:

# Increase scrollback — agents produce a lot of output
set -g history-limit 50000

# Show session name in status bar
set -g status-right "#{session_name} | %H:%M"

# Renumber windows when one is closed
set -g renumber-windows on

Apply without restarting tmux:

tmux source-file ~/.tmux.conf

The scrollback limit matters most. The default is 2,000 lines — an agent running a test suite fills that in minutes. Set it to at least 50,000.

How do you use tmux with git worktrees for parallel agents?

tmux handles session isolation but not filesystem isolation. Two Claude Code agents in separate tmux windows pointing at the same repo directory will conflict on file writes.

The fix is git worktrees: each agent gets its own working directory, all backed by a single .git store.

# Create worktrees
git worktree add ../project-auth-refactor -b auth-refactor
git worktree add ../project-api-migration -b api-migration

# Start agents in separate tmux sessions, each in its own worktree
tmux new -s claude-auth
cd ../project-auth-refactor && claude -p "..."
# Ctrl+b d

tmux new -s claude-api
cd ../project-api-migration && claude -p "..."

Each agent has its own branch, its own directory, and its own tmux session. No conflicts.

FAQ

Does tmux work the same way with Codex CLI and Aider?

Yes. tmux wraps any process. codex, aider, opencode all work identically — start them inside a named session and detach. The persistence is provided by tmux, not the agent.

What happens to tmux sessions if the server reboots?

They're gone. tmux sessions are in-memory processes, not persisted to disk. If your VPS restarts, you need to recreate your sessions. The tmux-resurrect plugin can restore session layout, but you'll still need to rerun the agent commands manually. Most VPS providers rarely reboot without notice, so this isn't a common problem in practice.

Can I use screen instead of tmux?

screen provides basic session persistence but lacks windows, modern scrollback, and active maintenance. For agent workflows where you want multiple sessions and a reasonable scrollback buffer, tmux is the better choice.

How do I know if the agent finished or is still running?

Attach to the session with tmux attach -t <name>. If the agent finished, you'll see the final output and a shell prompt. If it's still running, you'll see live output. To peek without fully attaching: tmux capture-pane -t <name> -p | tail -10.

What's the difference between detaching and killing a session?

Ctrl+b d detaches — the session and everything inside it keeps running. tmux kill-session -t <name> terminates the session and all processes in it immediately. Never use kill when you meant to detach.

Running agents without terminal management

tmux solves session persistence but leaves a monitoring gap: checking on three running agents means SSHing in and attaching to each session in turn. Grass closes that gap — sessions are persistent by default on always-on cloud VMs, and you can check in on running agents from your phone without opening a terminal. Free tier is 10 hours, no credit card.