Wendov1.0 · iOS & Android
English

Learn

tmux for coding agents: the minimum to keep them running

· 4 min read

If you start an agent straight from an SSH shell, it lives as long as that connection does. With tmux, the agent runs on the server whether you're connected or not, and you reattach whenever you like from your laptop or your phone. You don't need to know tmux deeply: about a dozen commands will do.

This is the companion to Mosh vs SSH on your phone, and it fits into the guide How to use Claude Code from your phone.

A session that survives

The command you'll use most:

tmux new-session -A -s agents

The -A flag means that if a session with that name exists, you attach to it; otherwise it's created. So you can always run the same thing. Inside, start your agent like you would in any shell:

cd ~/code/my-app
claude

To leave without killing anything, detach with Ctrl-b and then d. The agent keeps running. To get back in:

tmux attach -t agents

And to see which sessions exist:

tmux ls

If you close the terminal, Wi-Fi drops or SSH dies, it doesn't matter: the session stays on the server. That's the whole point.

Windows: one agent per window

A session has windows, like tabs. The typical situation: a long refactor running in window 2 while the tests run in window 3, and you poking at something in window 1.

Inside tmux, every shortcut starts with Ctrl-b:

  • c creates a new window.
  • , renames the current window.
  • n and p go to the next and previous window.
  • 0–9 jump to a window by number.
  • w opens a list to pick from.

You can also create and name windows from outside, or from a script:

tmux new-window -n claude -c ~/code/my-app
tmux new-window -n codex -c ~/code/my-app
tmux rename-window -t agents:2 refactor

Naming every window matters more than it seems. On your phone you'll read "claude", "codex" or "tests" in a small list, and "bash" four times in a row doesn't help.

Panes

If you want to see two things at once in the same window, split it:

  • Ctrl-b % splits the window into two columns.
  • Ctrl-b " splits it into two rows.
  • Ctrl-b o jumps to the next pane.
  • Ctrl-b x closes the current pane (it asks first).

On a phone screen, one window per task usually beats panes. On a laptop, use panes.

A small ~/.tmux.conf

Two settings change the experience a lot: mouse support and more history. The default history is about 2,000 lines, and an agent burns through that fast.

set -g mouse on
set -g history-limit 50000
set -g allow-rename off

With mouse on you can scroll with a finger or wheel and select panes by tapping them. allow-rename off stops the running program from renaming your window. Reload it with:

tmux source-file ~/.tmux.conf

To read what scrolled away without a mouse, enter copy mode with Ctrl-b [ and move up with the arrow keys or PgUp; leave with q. This is what Mosh doesn't give you and tmux does.

Several agents at once: git worktrees

Two agents editing the same directory trample each other. The clean fix is one worktree per agent: each works on its own branch in its own folder, sharing the same repository.

cd ~/code/my-app
git worktree add ../my-app-auth -b feature/auth
git worktree add ../my-app-reports -b feature/reports
git worktree list

Then a tmux window for each:

tmux new-window -n auth -c ~/code/my-app-auth
tmux new-window -n reports -c ~/code/my-app-reports

When a branch is merged and you're done with it:

git worktree remove ../my-app-auth

How Wendo uses it

Wendo is an SSH client for iOS and Android built to follow coding agents, and tmux is its central piece. The tmux integration is a Wendo Pro feature.

  • On connect, enter: choose tmux and, optionally, a session name. Wendo runs tmux new-session -A -s wendo (or whatever name you set), so every time you open the connection you land back in your session.
  • Machines shows each computer's sessions, windows and panes. Tap one and it opens right there.
  • With tmux, the workspaces sheet lets you switch windows, rename, close panes or windows, and create a session. You can also launch an agent (Claude Code, Codex, OpenCode or Gemini CLI) in a new window, or create a git worktree on a new branch and open it in its own window, which is what you just did by hand above.
  • Inbox alerts take you to the exact pane if Claude runs inside a multiplexer. Installing the hook is covered in alerts and approvals.

The terminal settings include applying global tmux options (titles, mouse and status bar). Everything is in the tmux docs; and if your connection is flaky, the sessions docs explain Mosh and ET.

Alternatives: zellij and herdr

If you prefer a different multiplexer, Wendo also works with zellij (zellij attach -c wendo) and herdr (herdr or herdr --session <name>). They need to be installed on your computer. The idea is the same: the agent lives on the server and you come and go.