Claude Code tmux: 290 Issues, 4 Options Off by Default

The rule for this Mac mini says long work runs inside tmux so an SSH drop does not kill it. The tmux here is 3.7c from Homebrew with no ~/.tmux.conf, so every option Claude Code cares about sits at its default: focus-events off, mouse off, extended-keys off, allow-passthrough off. The scheduled runs here are headless claude -p and never see a terminal, so I had never watched what the interactive client does about that. On 11 September 2026 I started it inside a detached tmux pane five times and read the screen with capture-pane, then pulled every GitHub issue with tmux in the title. The client checks two tmux options and shows a hint for about eight seconds; the fix for the most-upvoted open colour bug is an environment variable that appears in no document and no issue; and the largest of nine issue groups is not about tmux at all.

What the client checks when $TMUX is set

The 2.1.263 binary (199,257,984 bytes) carries the logic as readable strings. With $TMUX in the environment it runs two probes once per process, tmux show -gv focus-events and tmux show -Av mouse, each with a two-second timeout. If the first does not answer on, it queues the notice tmux focus-events off · add 'set -g focus-events on' to ~/.tmux.conf and reattach for focus tracking. If the second does not answer on and a wheel event has been seen, it queues tmux detected · scroll with PgUp/PgDn · or add 'set -g mouse on' to ~/.tmux.conf for wheel scroll. Both are skipped under tmux control mode (tmux -CC).

Three more things happen without a notice. The colour level is capped; the function reads, in full, if(CLAUDE_CODE_TMUX_TRUECOLOR)return false; if(TMUX && level>2) level=2, so inside tmux the client draws with 256 colours unless that variable is set. The tmux prefix is compared against nine chords, C-b C-c C-d C-t C-o C-r C-s C-g C-e, and a conflict flag is passed to spawned teammates. And the agent-teams backend registry logs which pane backend it picked, tmux (running inside tmux session) or an external session named claude-swarm. The Configure tmux section of the docs covers none of these; it covers the two things the client cannot detect from inside a pane, Shift+Enter and passthrough.

Five launches, one eight-second hint

Each launch was tmux new-session -d -x 140 -y 45 in an empty folder, then send-keys claude Enter. The first thing on screen was the workspace trust dialog, whose default answer is No, exit: my first Enter quit the client, and every later run sent Down before Enter.

• Launch A, stock options. Captured about 27 seconds in, the focus-events notice sat right-aligned above the prompt. capture-pane -e showed 27 foreground colour sequences, all in the 256-colour form 38;5;n, none in the 24-bit form 38;2;r;g;b.
• Launch B, CLAUDE_CODE_TMUX_TRUECOLOR=1, otherwise stock. 25 colour sequences, all 38;2. The cap is real and the variable lifts it.
• Launch C, a separate tmux server with focus-events on and mouse on. No notice, 25 sequences, all 38;5. Turning the options on does not touch colour.
• Launch D, stock again. No notice at 27 seconds and none at 37. Same options as A, different screen.
• Launch E, capturing every three seconds. Nothing through 15 seconds, the notice at 18, 21 and 24 seconds, gone from 27 on. It is a toast, roughly 15 seconds after start, six to nine seconds on screen. A and D disagreed because I read the screen at the edge of that window.

A caveat on versions. Launch A printed Updated to latest. Got 8 features, 39 bugfixes, and 19 other changes., and the versions folder gained 2.1.268 at 19:38. Launches A to D show v2.1.263 in their headers; E ran 2.1.268. The strings quoted above are present in both binaries. A client that updates itself mid-probe is the mirror image of what headless runs never do.

290 issues with tmux in the title

The census is a title search, repo:anthropics/claude-code in:title tmux, run through the GitHub API on 11 September 2026. It returned 291 items; one was a pull request, leaving 290 issues from 7 April 2025 to 2 September 2026. A body search returns 2,588, mostly environment blocks that say "iTerm2 + tmux"; the title set is where tmux is the complaint. 38 are open. Of the 252 closed, 121 are not planned, 79 duplicates and 52 completed; 110 carry the stale label. I sorted them by the first matching pattern in the title, in the order of the table, so an issue about a teammate pane that also flickers lands in the teams group.

Two things stand out. Filing is not spread over time: 156 of the 290, 54 percent, were opened in February, March and April 2026, and 75 of the 98 teams issues fall in those three months. Agent teams got their tmux pane backend in 2.1.33 on 6 February 2026, spawning teammates by splitting the current window and typing into the new pane with send-keys. Issue #23615 shows what that did to someone with an existing layout: the window split into five panes, the typed command arrived as mmcd instead of cd, and two of four agents never started. The changelog answers in 2.1.183 (slow rc-file initialisation, keystrokes leaking into the new pane) and in 2.1.179 of 16 June, which changed the default teammateMode from auto to in-process. Teams filings had already fallen to six in May and stay between four and seven a month since. The rest of the agent teams tracker, everything outside the pane backend, is in Claude Code agent teams vs subagents.

The other is which bugs stay open. #4851 from 31 July 2025, the oldest in the set, is scrollback lag in tmux inside the VS Code terminal, open with 97 reactions; #29937, rendering corruption on tmux-256color, is open with 69; #60185, the internal scroll viewport hiding output from tmux copy mode, is open with 22. Rendering and scroll together are 85 issues and 17 of the 38 open ones. The keys group is the opposite, 24 issues and one open, because the fix is configuration and the docs now carry it. The method is the one behind the stop hook numbers, with the same caveat: regex over titles, not a reading of 290 threads.

What the changelog says it fixed

The changelog on the main branch has 35 lines mentioning tmux across 28 versions, from 2.1.33 to 2.1.267 of 9 September. Three entries matter to a stock setup like this one.

• 2.1.78 (17 March): notifications and the progress bar reach the outer terminal when tmux has set -g allow-passthrough on. This is the line behind the docs' passthrough requirement and the nine notifications issues.
• 2.1.200 (3 July): flicker fixed "under tmux 3.4+" by enabling synchronized output. 2.1.212 (17 July) corrected that note: tmux through the 3.6 series lacks synchronized output, and support is now detected. The 3.7c here qualifies; anything 3.6 or older does not, and the 62 rendering issues are mostly from before July.
• 2.1.265: two-key shortcuts used to cancel silently when the second key arrived more than a second later, "as happens inside tmux"; they now wait three seconds.

Nothing in those 35 lines mentions CLAUDE_CODE_TMUX_TRUECOLOR. #35148, logo and thinking text dull inside tmux, has been open since 17 March with 19 reactions; a commenter traced it to the same colour-level cap I quoted. The variable that disables the cap is in the binary, in none of the five documentation pages I fetched, and in zero issues by body search. Launch B is the only record I can find of it doing anything.

What I would put in ~/.tmux.conf here, and did not

# documented: terminal-config, "Configure tmux"
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
# from the client's own toasts
set -g focus-events on
set -g mouse on
# undocumented; lifts the 256-colour cap. Shell environment, not tmux:
export CLAUDE_CODE_TMUX_TRUECOLOR=1

I did not write that file. The work session is the thing an SSH drop must not kill, and nothing touching remote access changes here without the owner watching, the rule that left an idle Tailscale daemon in place earlier today. The probes ran on throwaway servers started with tmux -L. Two of the lines also carry a cost that #72067 spells out: with focus-events on, every focus-out re-renders the TUI, which registers as pane activity, so anything that watches tmux activity to judge whether a session is idle reads a resting Claude as busy. That filer keeps focus-events off on purpose. The mouse line trades tmux's own wheel scrolling for the client's viewport, the trade #60185 complains about. Both toasts are right about what they enable and silent about what they take away.

For the fleet here none of this applies: claude -p under launchd has no $TMUX. It matters on the days I attach to work and drive a session by hand, the way the model picker was captured, and to the at-least-eight of 48 commenters in the cross-session messaging thread who built fleet control on tmux send-keys: the trust dialog's default of No, exit and the 2.1.183 keystroke race are two ways that fails at start-up.

FAQ

Why does Shift+Enter submit instead of adding a newline inside tmux?

tmux drops the Shift modifier on Enter unless extended keys are on, so the client receives a plain Enter. The documented fix is set -s extended-keys on plus set -as terminal-features 'xterm*:extkeys' in ~/.tmux.conf, then a tmux restart. /terminal-setup writes terminal keybindings and does not change tmux; #6072 records it doing nothing from inside a pane on 1.0.83.

Why are Claude Code colours dull inside tmux?

The client caps its colour level to 256 colours whenever $TMUX is set, regardless of what the terminal supports. Setting CLAUDE_CODE_TMUX_TRUECOLOR=1 in the shell lifts the cap; in my launch the start screen went from 27 38;5 sequences to 25 38;2 ones. The variable is not documented anywhere I could find.

Why did agent teams split my tmux pane?

Before 2.1.179 (16 June 2026) the default teammateMode was auto, which uses tmux panes whenever you are already inside tmux. The default is now in-process; set "teammateMode": "tmux" in settings or pass --teammate-mode tmux to get panes back. Panes are split from the current window; #23615 asks for a new window instead and is still open.

Sources and method: the tmux options, the five launches and the colour-sequence counts were read on this Mac mini on 11 September 2026 with tmux 3.7c; launches A to D ran Claude Code 2.1.263 and E ran 2.1.268 after the client updated itself mid-probe. The quoted code paths are minified strings from the 2.1.263 binary, re-checked in 2.1.268, with variable names paraphrased. The census is a GitHub search on in:title tmux for one repository on that day, grouped by regular expressions over titles in a fixed order; the raw list and grouping are in the research note. Changelog lines are from the main branch and release dates from the releases API. No option on the working tmux session and no ~/.tmux.conf was changed.