tmux Claude Code

The important boundary is the machine doing the work. tmux preserves a terminal session across a disconnect. It cannot make a sleeping laptop compute, keep a powered-off server alive, or restart a crashed Claude process. Anthropic explicitly recommends tmux or screen for a remote Claude session that must survive an SSH disconnect. Anthropic Remote Control documentation.

Start With the Documented tmux Config

Put the configuration on the machine running Claude Code. For remote work, that means the remote host's ~/.tmux.conf. Install tmux through that host's package manager if needed, and check tmux -V and claude --version there before continuing.

Merge this block into ~/.tmux.conf. The first three lines are Anthropic's documented setup; the commented mouse preference is optional and is not an Anthropic requirement.

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

# Optional preference: enable mouse interaction in tmux.
# set -g mouse on

Passthrough lets notifications and progress updates reach the outer terminal. Extended keys let tmux distinguish Shift+Enter from Enter. Apply the configuration to a running tmux server with tmux source-file ~/.tmux.conf; a new server loads the file on startup. Anthropic terminal configuration.

If you have no tmux server yet, create the first session below before running the reload command. Keep third-party plugins out of the initial setup: none is required for this workflow.

Give Each Worktree Its Own Named Session

A Git worktree is another checkout with its own files and branch, sharing the repository's history. A tmux session is a named collection of terminal windows; a pane is a subdivision of a window. Think of the worktree as the workbench and tmux as the room you can leave and re-enter. Anthropic worktree guide.

Use a matching naming scheme so the session name tells you which checkout you are entering. This is a suggested layout, not a Claude Code default:

The following first-time example assumes an existing repository at ~/src/project, at least one commit, and unused branch, directory and session names. Replace dev@devbox and the project path. Run it from your laptop's ordinary shell, outside tmux. The worktree commands follow Anthropic's manual workflow; the named-session arrangement is the recipe for this guide.

ssh dev@devbox
cd ~/src/project

git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix -b bugfix

tmux new-session -d -s cc-feature-a -n claude -c "$HOME/src/project-feature-a"
tmux new-session -d -s cc-bugfix -n claude -c "$HOME/src/project-bugfix"

tmux attach-session -t cc-feature-a
# Now inside the feature worktree's tmux shell:
claude

After SSH connects, enter the remaining commands on the remote host. The two detached sessions initially contain shells. Attaching to one and running claude starts its coding session visibly, including any normal setup prompts. Detach, attach to cc-bugfix, and run claude there when you want the second task active.

Worktrees need their own project setup, including dependencies and any required local configuration. Check the directory and branch before giving Claude an editing task. Anthropic manual worktree workflow.

For an optional test shell in the feature checkout, run tmux new-window -t cc-feature-a -n checks -c "$HOME/src/project-feature-a" from a shell on the host. Keep checks beside the task they belong to. Avoid using the main checkout as a shared scratch directory for both agents.

If you also use Codex, our Codex CLI worktree guide covers that tool's workflow separately.

Detach, Close the Laptop, and Reattach Over SSH

With tmux's default prefix, press Ctrl+B, release both keys, then press D. That detaches the client and returns you to the remote shell. You can now disconnect SSH. Leave Claude running inside its session.

When you return, run ssh dev@devbox, then tmux list-sessions, then tmux attach-session -t cc-feature-a. Use the same remote host and user account. From your laptop, the single-command equivalent is ssh -t dev@devbox 'tmux attach-session -t cc-feature-a'.

These keys assume the default prefix. If you already changed it, use your configured prefix instead. Within tmux, switch sessions rather than nesting another tmux client.

Reattaching connects to the existing terminal process. If that process ended, conversation recovery is a different operation: claude --continue resumes the latest conversation in the current directory, and claude --resume opens a picker. Neither is a substitute for keeping the original process alive. Anthropic session workflow.

If you want phone or browser access, see Claude Code Remote Control. Its execution still stays on the host, which must remain on. Anthropic Remote Control.

Add an Agent Team When the Work Needs Coordination

Agent teams are experimental and disabled by default. In a tmux shell, start a fresh interactive lead with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode tmux. The environment variable enables teams for that launch; the flag selects split panes. Anthropic agent-team setup.

The current default is in-process. auto uses split panes inside tmux and falls back when needed; tmux selects split-pane mode with terminal detection. A persistent preference uses teammateMode in ~/.claude/settings.json. Split panes give teammates separate visible terminals. Anthropic lists VS Code's integrated terminal, Windows Terminal and Ghostty as unsupported for this mode. Anthropic display modes and limitations.

For a first trial, I would give the lead this narrow assignment:

Your manually started cc-feature-a and cc-bugfix sessions do not become teammates merely because tmux holds both. Treat a team as a separate choice about who assigns work and reconciles findings. Prefer Claude Code subagents when you want focused delegation within one session.

A pane is not a separate checkout. Assign different files or use separate worktrees for independent editing. Teams also use more tokens; tmux does not reduce that consumption. Reattachment preserves a live terminal, while /resume does not restore in-process teammates. Anthropic team guidance.

Five Jobs This Layout Fits

I would prioritize these uses in this order. Each is a possible workflow, not a measured productivity claim.

Measure the interruption cost before adding more automation. For illustration, five interruptions that each require four minutes of rebuilding context cost twenty minutes a week. Those are hypothetical inputs, not benchmark results. Record your own recovery time, setup time and review time; the workflow earns its place if the total improves. More simultaneous agents are not automatically a better deal.

Two Small Tools Worth Building Around This

The stronger opportunity is a worktree-and-session launcher for development teams. A platform team could pay for consistent task names, checkout paths and attach commands across its developers. The smallest useful version would create or locate a worktree, open its named tmux session, and show the branch and path before launching Claude. It should ask before cleaning up a checkout.

DataForSEO's US keyword estimate, retrieved October 12, 2026, is 480 monthly searches for “tmux claude code.” That is a narrow signal of setup interest, not a count of buyers. The catch is that a short internal script may be enough; a paid product needs team-specific setup or support that saves recurring work.

A remote-session inventory is a second, narrower product. A small engineering team could use one place to record approved host aliases, session names and checkout paths, with a copyable SSH attach command. Start with discovery and navigation, then add lifecycle controls only if users need them.

The same DataForSEO check estimates 1,600 monthly US searches for “claude code remote” and 70 for “claude code remote ssh.” The broader query includes people seeking other remote interfaces, so it does not validate an SSH product by itself. The catch is access management: the inventory must respect each developer's existing host permissions. Interview remote-first teams before building a dashboard.

Questions You Will Actually Hit

Your Monday move: choose one remote task, create its worktree and named session, and verify that you can detach and reattach before leaving it unattended. Add a second independent task only after that path is routine.

If your team needs this workflow built into its development environment, we build production AI systems.