Docs · AI agents · Claude Code 2.1.312 · tmux 3.8
Running Claude Code in tmux: persistent AI agents
Start Claude Code inside a tmux session and it keeps working when your SSH connection drops or you close the terminal: run tmux new -A -s claude, then claude, detach with Ctrl+b d, and come back with tmux attach -t claude. Add four lines to ~/.tmux.conf so Shift+Enter and notifications work, and use Claude Code's own --tmux and agent-team split panes when you want it to build the layout for you.
On this page
- Why run Claude Code inside tmux?
- tmux settings Claude Code needs
- Claude Code's built-in tmux support
- A three-pane layout for agent work
- Build the workspace with one command
- Unattended runs: claude -p in detached sessions
- Notifications and logging: know when an agent needs you
- Troubleshooting Claude Code in tmux
- FAQ
Quick answer
How do I run Claude Code in tmux?
- Start or reattach a session:
tmux new -A -s claude(createsclaude, or attaches if it exists). - Run the agent in it:
claude - Leave it running: press Ctrl+b d to detach. Close the laptop; the agent keeps going.
- Come back:
tmux attach -t claude, from the same machine or over SSH. - Once: add the four tmux settings Anthropic documents for Shift+Enter, notifications and the progress bar.
Facts about Claude Code on this page come from Anthropic's documentation at code.claude.com, read on 28 October 2026 (Claude Code 2.1.312, released 27 October 2026), and from running the 2.1.312 CLI. Everything on the tmux side was run on tmux 3.8, and on 3.4 where we say so.
Why run Claude Code inside tmux?
An agent run can take minutes or hours. In a plain terminal tab the agent is a child of that tab: close the tab, lose Wi-Fi on an SSH connection, or let the laptop's SSH session time out, and the shell gets a hangup signal and the run stops halfway through an edit. In tmux, the agent's parent is the tmux server, which does not depend on your terminal or SSH connection. Only the tmux client goes away; you reattach and find the agent where it is.
The second reason is visibility. One tmux window can hold the agent, the dev server it is breaking, and a shell for git diff and tests, all at once, and the same layout comes back every time you attach.
| What happens | Plain terminal tab | tmux session | claude --bg background session |
|---|---|---|---|
| You close the terminal window | Run stops | Keeps running | Keeps running |
| SSH connection drops | Run stops | Keeps running on the server | Not documented for SSH |
| You want agent, server and shell side by side | Several tabs | Panes in one window | Agent view lists sessions |
| Machine reboots | Gone | Gone (layout can be restored with tmux-resurrect) | Shown as failed; restart from the saved conversation |
Claude Code also has its own background sessions: claude --bg "task" starts one, claude agents lists them and claude attach <id> opens one. Anthropic documents that they keep running when you close the shell, run on your own machine through a supervisor process, and stop on reboot. They are a good fit on a laptop. On a remote server, tmux is still the simpler choice: it is already installed almost everywhere, it survives SSH drops by design, and it shows the agent next to everything else.
tmux settings Claude Code needs
Without these lines, Shift+Enter inside tmux submits the prompt instead of adding a newline, and Claude Code's desktop notifications and progress bar never reach your terminal. The first four lines are exactly the ones in Anthropic's terminal configuration guide.
# From Anthropic's terminal configuration docs (Claude Code 2.1.312)
set -g allow-passthrough on
set -g focus-events on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
# Optional: also forward notifications from agents in background windows
# set -g allow-passthrough all
# Long agent runs produce a lot of output (default is 2000 lines)
set -g history-limit 50000Reload with tmux source-file ~/.tmux.conf, then detach and attach again (focus events and key modes are set up when a client attaches) and restart Claude Code. If Shift+Enter still submits, check that echo $TERM outside tmux starts with xterm; if it does not, put your terminal's TERM in place of xterm*. Ctrl+J, or \ then Enter, always inserts a newline.
| Line | What it does | tmux default |
|---|---|---|
allow-passthrough on | Lets Claude Code's notification and progress escape sequences through tmux to the outer terminal. | off |
focus-events on | Tells programs in the pane when you switch to or away from the terminal. Anthropic lists it with the others; Neovim uses it too. | off |
extended-keys on + extkeys | Lets tmux tell Shift+Enter apart from Enter and pass it on to Claude Code. | off |
history-limit 50000 | Keeps more scrollback per pane, so you can scroll back through a long run in copy mode. | 2000 |
Claude Code's built-in tmux support
Claude Code can create tmux sessions and panes itself in two places: worktree sessions with --tmux, and agent teams in split-pane mode.
Worktree sessions: claude -w name --tmux
# New git worktree + its own tmux session, attached right away
claude -w feature-auth --tmux
# Same, but force classic tmux even in iTerm2 (otherwise iTerm2 native panes)
claude -w feature-auth --tmux=classic
# Agent team with each teammate in its own tmux pane
claude --teammate-mode tmux--tmux requires --worktree (-w). Claude Code creates the worktree under .claude/worktrees/<name>/ on a branch called worktree-<name>, starts a tmux session running claude in that directory, and attaches you to it. When we ran claude -w feat --tmux=classic in a repository called ccrepo, the session was named ccrepo_worktree-feat. Run it from a directory you have already opened Claude Code in: an untrusted directory stops with Workspace trust not yet accepted.
Agent teams in tmux panes
Agent teams (experimental) let one Claude Code session lead several teammates, each a separate Claude Code instance. Turn them on with the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, either in your shell or in ~/.claude/settings.json, then ask Claude for a team in plain language. How teammates are shown is the teammateMode setting or the --teammate-mode flag (the flag is experimental and is not listed in claude --help):
| Value | What you get |
|---|---|
in-process (default) | All teammates inside your one terminal. Arrow keys pick a teammate in the agent panel, Enter opens it. Works in any terminal. |
auto | Split panes when you are already inside a tmux session (or in iTerm2 with the it2 CLI), otherwise in-process. |
tmux | Split-pane mode; Claude Code picks tmux or iTerm2 from your terminal. |
iterm2 | iTerm2 native panes. Needs the it2 CLI and iTerm2's Python API. |
{
"env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
"teammateMode": "auto"
}Split-pane mode is not supported natively in VS Code's terminal, Windows Terminal or Ghostty, so in those terminals start claude inside tmux and use auto. Anthropic also notes that tmux "traditionally works best on macOS" for this, and suggests tmux -CC in iTerm2 as the entry point there. If teammates never appear as panes, check that which tmux finds tmux in the PATH Claude Code sees. If a team's tmux session outlives the lead, find it with tmux ls and remove it with tmux kill-session -t <name>.
A three-pane layout for agent work
Give the agent the big pane on the left, the dev server top right, and a shell for git diff, tests and quick checks bottom right.
![A real tmux 3.8 window with pane titles: the Claude Code CLI on the left (here printing its tmux flags), a dev server and a shell. Window 1 shows the [waiting] flag from the notification hook below.](/img/real/claude-agent-layout.png?v=20261028)
How this was captured
Captured 2026-10-29 04:52 UTC from a real xterm window running tmux 3.8 on Ubuntu 24.04. Nothing is mocked up. The commands that set up the screen:
# ~/.tmux.conf: set -g pane-border-status top
# ~/.tmux.conf: set -g pane-border-format ' #{pane_index}: #{pane_title} '
# ~/.tmux.conf: set -g window-status-format '#I:#W#{?@claude, [#{@claude}],}#{?window_flags,#{window_flags}, }'
# ~/.tmux.conf: set -g window-status-current-format '#I:#W#{?@claude, [#{@claude}],}#{?window_flags,#{window_flags}, }'
tmux new-session -d -s ai-dev -n workspace -x 120 -y 31
tmux split-window -h -t ai-dev:workspace
tmux split-window -v -t ai-dev:workspace.1
tmux new-window -d -t ai-dev: -n agent-2
tmux select-pane -t ai-dev:workspace.0 -T agent
tmux select-pane -t ai-dev:workspace.1 -T 'dev server'
tmux select-pane -t ai-dev:workspace.2 -T shell
tmux send-keys -t ai-dev:workspace.0 'cd ~/projects/app; git init -q; clear; claude --version; claude --help | grep -A2 -e '"'"'--tmux '"'"' -e '"'"'-w, --worktree'"'"' | sed '"'"'s/ */ /g'"'"'' Enter
tmux send-keys -t ai-dev:workspace.1 'cd ~/projects/app; clear; python3 -m http.server 8000' Enter
tmux send-keys -t ai-dev:workspace.2 'cd ~/projects/app; clear; curl -s -o /dev/null -w '"'"'%{http_code}\n'"'"' localhost:8000; git status -s; tmux list-panes -F '"'"'#{pane_index} #{pane_title} #{pane_current_command}'"'"'' Enter
tmux set -w -t ai-dev:agent-2 @claude waiting
tmux select-pane -t ai-dev:workspace.0| Do this | Keys |
|---|---|
| Split left / right | Ctrl+b % |
| Split the right pane top / bottom | Ctrl+b " |
| Move between panes | Ctrl+b ← and the other arrows, or click (mouse is on by default in 3.8) |
| Zoom the agent pane to full size and back | Ctrl+b z |
| Name the pane (shown in the border) | Ctrl+b T (tmux 3.8) or tmux select-pane -T agent |
| One more agent in its own window | Ctrl+b c, then claude |
To show pane titles in the borders, as in the screenshot, add set -g pane-border-status top and set -g pane-border-format ' #{pane_index}: #{pane_title} '. More about splitting, resizing and layouts is on the panes and windows page.
Build the workspace with one command
A short script builds the layout, starts the agent and the dev server, and attaches. Run it again and it reattaches instead of creating a second copy. We tested it on tmux 3.8 with stand-in commands.
#!/usr/bin/env bash
# launch-ai.sh: Claude Code + dev server + shell in one tmux window
set -euo pipefail
SESSION="${SESSION:-ai-dev}"
DIR="${1:-$PWD}"
if ! tmux has-session -t "=$SESSION" 2>/dev/null; then
# -P -F prints the new pane's ID, so this works with any base-index
agent=$(tmux new-session -d -s "$SESSION" -n workspace -c "$DIR" -P -F '#{pane_id}')
tmux send-keys -t "$agent" 'claude' Enter
server=$(tmux split-window -h -t "$agent" -c "$DIR" -P -F '#{pane_id}')
tmux send-keys -t "$server" 'npm run dev' Enter
tmux split-window -v -t "$server" -c "$DIR"
tmux select-pane -t "$agent"
fi
# Attach, or switch if we are already inside tmux
if [ -n "${TMUX:-}" ]; then
tmux switch-client -t "=$SESSION"
else
tmux attach-session -t "=$SESSION"
fiRun it as launch-ai.sh ~/src/app. The = in -t "=$SESSION" asks for an exact name match, so ai-dev never matches ai-dev-2. If you prefer a YAML file, tmuxinator describes the same layout:
name: ai-dev
root: ~/src/app
windows:
- workspace:
layout: main-vertical
panes:
- claude
- npm run dev
- git statusStart it with tmuxinator start ai-dev. Scripting tmux in general (send-keys, capture-pane, hooks, tmuxp and libtmux) is covered in tmux scripting and automation.
Unattended runs: claude -p in detached sessions
claude -p "prompt" runs one task without the interactive interface and exits. Put each run in its own detached tmux session and several can work at once while you are away; tmux ls shows which are still running, because a session closes when its command exits.
# Backend: may edit files and run the test suite, nothing else
tmux new-session -d -s agent-backend -c ~/src/api "claude -p 'Refactor the auth module to support OAuth2, then run the tests' --permission-mode acceptEdits --allowedTools 'Bash(npm test *)' > ~/logs/backend.log 2>&1"
# Tests in another repo, at the same time; prompts nobody can answer are denied
tmux new-session -d -s agent-tests -c ~/src/web "claude -p 'Write unit tests for src/utils' --permission-mode auto --permission-prompts none > ~/logs/tests.log 2>&1"
# Which runs are still going?
tmux ls
tail -f ~/logs/backend.logNobody is there to approve actions, so decide up front what Claude may do. The modes below are from Anthropic's headless documentation:
| Option | What it allows without asking |
|---|---|
--allowedTools 'Bash(npm test *)' | Exactly the tools and commands you list. |
--permission-mode acceptEdits | File edits and common file commands (mkdir, mv, cp…); other shell commands still need an allow rule. |
--permission-mode auto | A classifier reviews each action instead of you. Add --permission-prompts none (Claude Code 2.1.259 or later) so anything that would still need a person is denied instead of waiting. |
--permission-mode dontAsk | Denies everything that would prompt; only pre-approved actions run. Good for locked-down CI. |
--dangerously-skip-permissions | Everything (same as bypassPermissions). Only inside a throwaway container or VM with no credentials you care about. |
Notifications and logging: know when an agent needs you
The most common question with several agents in tmux is how to tell which one is waiting for input, for example at a "Do you want to proceed?" permission prompt. There are three ways to get a signal out of tmux, and they combine.
1. Desktop notifications and the terminal bell
Anthropic documents that Claude Code sends desktop notifications itself in Ghostty, Kitty and iTerm2 (iTerm2 also needs Settings → Profiles → Terminal → Notification Center Alerts and, under Filter Alerts, Send escape sequence-generated alerts). Inside tmux these need allow-passthrough from the settings above. In any other terminal, ask for the terminal bell instead:
{
"preferredNotifChannel": "terminal_bell"
}A bell needs no passthrough. tmux marks the window with ! in the status line and passes the bell to your terminal (the 3.8 defaults are monitor-bell on and bell-action any, so this already works for background windows).
2. A "waiting" flag in the tmux status line, from a hook
Claude Code runs Notification hooks when it needs you: permission_prompt fires when a permission prompt has waited about six seconds, and idle_prompt about 60 seconds after Claude finished and you have not typed. Hooks inherit Claude Code's environment, so inside tmux they know $TMUX_PANE. These hooks set a window option that the status line shows, and clear it when work resumes:
{
"hooks": {
"Notification": [{ "hooks": [{ "type": "command",
"command": "[ -z \"$TMUX_PANE\" ] || tmux set -w -t \"$TMUX_PANE\" @claude waiting 2>/dev/null || true" }] }],
"Stop": [{ "hooks": [{ "type": "command",
"command": "[ -z \"$TMUX_PANE\" ] || tmux set -w -t \"$TMUX_PANE\" @claude done 2>/dev/null || true" }] }],
"UserPromptSubmit": [{ "hooks": [{ "type": "command",
"command": "[ -z \"$TMUX_PANE\" ] || tmux set -wu -t \"$TMUX_PANE\" @claude 2>/dev/null || true" }] }],
"PostToolUse": [{ "hooks": [{ "type": "command",
"command": "[ -z \"$TMUX_PANE\" ] || tmux set -wu -t \"$TMUX_PANE\" @claude 2>/dev/null || true" }] }]
}
}# Show [waiting] or [done] after the window name
set -g window-status-format '#I:#W#{?@claude, [#{@claude}],}#{?window_flags,#{window_flags}, }'
set -g window-status-current-format '#I:#W#{?@claude, [#{@claude}],}#{?window_flags,#{window_flags}, }'The || true matters: a Stop hook that exits with code 2 tells Claude Code to keep going. We tested the commands and the format on tmux 3.8 and 3.4, inside and outside tmux; the screenshot above shows the result. If you use the hooks outside tmux they do nothing.
3. Silence detection and screen checks (no Claude Code setup)
# Flag a window that has printed nothing for 30 s (finished or waiting)
set -w monitor-silence 30A silent window shows ~ in the status line (#{window_silence_flag}). It cannot tell "finished" from "waiting", but it works for any agent. For a quick check from a script, look at the screen text of every pane; this depends on Claude Code's prompt wording ("Do you want to proceed?" in 2.1.312), so prefer the hooks:
#!/usr/bin/env bash
tmux list-panes -a -F '#{pane_id} #{session_name}:#{window_index}.#{pane_index}' |
while read -r id where; do
tmux capture-pane -p -t "$id" | grep -q 'Do you want to' && echo "$where is waiting for you"
doneLogging what an agent did
Claude Code already saves every conversation as a JSONL transcript under ~/.claude/projects/, and claude --resume reopens it; scripted runs can use --output-format json. To also keep the raw terminal output of a pane, escape codes included, pipe it to a file. -o toggles the pipe, so the same command stops it:
tmux pipe-pane -o "cat >> ~/claude-session-$(date +%Y%m%d).log"To save what is on screen and in the history once, use tmux capture-pane -p -S - > file (see copy mode and capture-pane).
iTerm2 3.7 adds its own Claude Code integration (iTerm2 → Install Claude Code Integration), which installs hooks that show each session's state in iTerm2's Session Status tool. It works on iTerm2's own sessions; the tmux status approach above works in any terminal.
Troubleshooting Claude Code in tmux
| Symptom | Fix |
|---|---|
| Shift+Enter submits instead of adding a newline | Add the extended-keys lines above, detach and reattach, restart Claude Code. Use Ctrl+J meanwhile. Run /terminal-setup outside tmux, not inside it: it writes to the outer terminal's settings. |
| No notifications from agents in other windows | set -g allow-passthrough all, or use the bell or the hook flag. |
| Colors look washed out | Tell tmux your terminal has 24-bit color; see true color in tmux. |
sessions should be nested with care, unset $TMUX to force | You ran tmux inside tmux, for example from a shell profile. Guard it as below; details on nested sessions. |
API Error … ECONNRESET | A network error from Claude Code, not from tmux. See ECONNRESET in a tmux pane. |
| A batch session vanished before you saw the result | set -g remain-on-exit failed-key (3.8), or end the command with ; read. |
| Teammates do not open in panes | Start the lead inside tmux with teammateMode auto or tmux, and check which tmux. |
To land in your agent session every time you SSH into a server, add this to the server's shell profile. The $TMUX check stops it running again inside tmux:
# Attach to (or create) "main" on SSH login, unless already inside tmux
if [ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ]; then
tmux new -A -s main
fiClaude Code's Remote Control (claude --remote-control) is a different tool: it lets you drive a running Claude Code session from claude.ai or the Claude app. It does not replace tmux for keeping the process alive on a server, and the two work together.
FAQ
Why should I run Claude Code inside a tmux session?
Because the agent then belongs to the tmux server, not to your terminal window or SSH connection. Closing the window or losing the connection only ends the tmux client; Claude Code keeps working and you reattach with tmux attach. tmux also lets you watch the agent, the dev server and a shell in one window.
Does Claude Code have a tmux mode?
Yes, two. claude -w <name> --tmux creates a git worktree and a tmux session for it (iTerm2 native panes when available, --tmux=classic forces tmux). Agent teams can show each teammate in its own tmux pane with teammateMode auto or tmux, or claude --teammate-mode tmux.
Can I run several Claude Code agents in parallel with tmux?
Yes. Give each its own window (Ctrl+b c) or its own session (tmux new -s agent-api, tmux new -s agent-web). Use separate git worktrees (claude -w name) so they do not edit the same files, and the hook flag above to see which one is waiting.
What happens if SSH drops while Claude Code is editing files?
Nothing is lost. Claude Code keeps running inside the tmux server on that machine. Reconnect and run tmux attach to see where it is.
How do I know when Claude Code in tmux is waiting for input?
Use a Notification hook that runs tmux set -w -t "$TMUX_PANE" @claude waiting and show @claude in the status line (see the hook config), or set preferredNotifChannel to terminal_bell so the window gets tmux's bell flag.
How do I scroll back through Claude Code's output in tmux?
With the mouse wheel (mouse is on by default in tmux 3.8), or Ctrl+b [ then arrow keys or PgUp. Raise history-limit for long runs. More on the copy mode page.
How do I log all of Claude Code's terminal output?
Claude Code saves each conversation under ~/.claude/projects/, and claude -p --output-format json gives a machine-readable result. For the raw terminal stream, use tmux pipe-pane -o "cat >> ~/claude.log".
Keep learning
Something wrong or out of date on this page? Email hello@tmux.app and we will fix it.