## 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](/content/?ref=codeongrass.com) 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](/content/blog/how-to-keep-claude-code-running-after-terminal-close/index.html) first. This guide assumes you've made that decision and focuses on working with tmux day-to-day.

* * *

## Step 1 — Install tmux

```bash
sudo apt update && sudo apt install -y tmux
```

Verify:

```bash
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.

```bash
tmux new -s claude-auth-refactor
```

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

```bash
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:

```bash
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:

```bash
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.

```bash
# 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.

```bash
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?

| Action | Command |
| --- | --- |
| New named session | `tmux new -s <name>` |
| Detach | `Ctrl+b d` |
| List sessions | `tmux ls` |
| Attach to session | `tmux attach -t <name>` |
| Kill a session | `tmux kill-session -t <name>` |
| New window | `Ctrl+b c` |
| Switch to window N | `Ctrl+b <N>` |
| Rename window | `Ctrl+b ,` |
| Scroll through output | `Ctrl+b [` then arrows / PageUp (q to exit) |
| Split pane vertical | `Ctrl+b %` |
| Split pane horizontal | `Ctrl+b "` |

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`:

```bash
# 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:

```bash
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](/content/blog/parallel-coding-agents-worktree-isolation-ownership/index.html): each agent gets its own working directory, all backed by a single `.git` store.

```bash
# 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](https://github.com/tmux-plugins/tmux-resurrect?ref=codeongrass.com) 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](/content/blog/grass.com) 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.