[tmux.app]
tmux 3.8

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.

Updated Tested on tmux 3.811 min read

On this page
  1. Why run Claude Code inside tmux?
  2. tmux settings Claude Code needs
  3. Claude Code's built-in tmux support
  4. A three-pane layout for agent work
  5. Build the workspace with one command
  6. Unattended runs: claude -p in detached sessions
  7. Notifications and logging: know when an agent needs you
  8. Troubleshooting Claude Code in tmux
  9. FAQ

Quick answer

How do I run Claude Code in tmux?

  1. Start or reattach a session: tmux new -A -s claude (creates claude, or attaches if it exists).
  2. Run the agent in it: claude
  3. Leave it running: press Ctrl+b d to detach. Close the laptop; the agent keeps going.
  4. Come back: tmux attach -t claude, from the same machine or over SSH.
  5. 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 happensPlain terminal tabtmux sessionclaude --bg background session
You close the terminal windowRun stopsKeeps runningKeeps running
SSH connection dropsRun stopsKeeps running on the serverNot documented for SSH
You want agent, server and shell side by sideSeveral tabsPanes in one windowAgent view lists sessions
Machine rebootsGoneGone (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.

~/.tmux.conf
# 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 50000

Reload 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.

LineWhat it doestmux default
allow-passthrough onLets Claude Code's notification and progress escape sequences through tmux to the outer terminal.off
focus-events onTells 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 + extkeysLets tmux tell Shift+Enter apart from Enter and pass it on to Claude Code.off
history-limit 50000Keeps 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

Claude Code 2.1.312
# 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):

ValueWhat 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.
autoSplit panes when you are already inside a tmux session (or in iTerm2 with the it2 CLI), otherwise in-process.
tmuxSplit-pane mode; Claude Code picks tmux or iTerm2 from your terminal.
iterm2iTerm2 native panes. Needs the it2 CLI and iTerm2's Python API.
~/.claude/settings.json
{
  "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.

Real screenshot · tmux 3.8A 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.
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.
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 thisKeys
Split left / rightCtrl+b %
Split the right pane top / bottomCtrl+b "
Move between panesCtrl+b ← and the other arrows, or click (mouse is on by default in 3.8)
Zoom the agent pane to full size and backCtrl+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 windowCtrl+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.

~/bin/launch-ai.sh
#!/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"
fi

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

~/.config/tmuxinator/ai-dev.yml
name: ai-dev
root: ~/src/app
windows:
  - workspace:
      layout: main-vertical
      panes:
        - claude
        - npm run dev
        - git status

Start 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.

parallel unattended runs
# 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.log

Nobody is there to approve actions, so decide up front what Claude may do. The modes below are from Anthropic's headless documentation:

OptionWhat it allows without asking
--allowedTools 'Bash(npm test *)'Exactly the tools and commands you list.
--permission-mode acceptEditsFile edits and common file commands (mkdir, mv, cp…); other shell commands still need an allow rule.
--permission-mode autoA 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 dontAskDenies everything that would prompt; only pre-approved actions run. Good for locked-down CI.
--dangerously-skip-permissionsEverything (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.

How a Claude Code alert gets out of tmux Claude Code in a tmux pane can signal you in three ways. A desktop notification is an escape sequence that tmux only forwards when allow-passthrough is on (visible panes) or all (any pane); the outer terminal such as Ghostty, Kitty or iTerm2 then shows a system notification. A terminal bell, enabled with preferredNotifChannel terminal_bell, needs no passthrough: tmux marks the window with a bell flag and passes the bell on. A Notification hook runs a shell command, for example tmux set to put a waiting flag in the status line. Claude Code in a tmux pane needs you / done Desktop notification escape sequence, wrapped allow-passthrough on | all Terminal bell preferredNotifChannel tmux bell flag ! Notification hook runs a shell command tmux set -w @claude … Outer terminal Ghostty, Kitty, iTerm2: system notification any terminal: bell, dock bounce, sound tmux status line 1:agent-2 [waiting]
Desktop notifications need passthrough, a bell needs nothing, and a hook can write straight into the tmux status line.

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:

~/.claude/settings.json
{
  "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:

~/.claude/settings.json (hooks)
{
  "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" }] }]
  }
}
~/.tmux.conf
# 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)

~/.tmux.conf or the command line
# Flag a window that has printed nothing for 30 s (finished or waiting)
set -w monitor-silence 30

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

agents-waiting.sh
#!/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"
done

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

raw pane log
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

SymptomFix
Shift+Enter submits instead of adding a newlineAdd 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 windowsset -g allow-passthrough all, or use the bell or the hook flag.
Colors look washed outTell tmux your terminal has 24-bit color; see true color in tmux.
sessions should be nested with care, unset $TMUX to forceYou ran tmux inside tmux, for example from a shell profile. Guard it as below; details on nested sessions.
API Error … ECONNRESETA network error from Claude Code, not from tmux. See ECONNRESET in a tmux pane.
A batch session vanished before you saw the resultset -g remain-on-exit failed-key (3.8), or end the command with ; read.
Teammates do not open in panesStart 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:

~/.bashrc or ~/.zshrc on the server
# Attach to (or create) "main" on SSH login, unless already inside tmux
if [ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ]; then
  tmux new -A -s main
fi

Claude 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.