Claude Code in tmux: scrolling, panes and send-keys

What a multiplexer actually gives you

tmux is a terminal multiplexer: it runs in a terminal and lets several other terminal programs run inside it, each with its own terminal managed by tmux, all reached through the single window you are looking at. Its own documentation names three uses, and two of them are why people put a coding agent inside it.

The first is survival. Programs inside tmux can be detached from the terminal they were started in and reattached later, from the same window or a different one. That covers a dropped SSH connection or a terminal window you closed by mistake. When tmux is running on the remote machine rather than on the laptop, it also covers the laptop itself: the work was never running there, so a flat battery or a shut lid changes nothing.

The second is layout. A pane is a rectangle of the terminal holding one program. A window holds one or more panes. A session holds one or more windows, and each session has a name that has to be unique. Ctrl+B % splits the current pane side by side and Ctrl+B " splits it one above the other. Start one Claude Code session per pane and you have all of them on one screen at once.

What tmux does not do is give each pane its own copy of your files. Every session keeps running in the directory you started it in, which is the shared-file problem and not a pane problem. Our guide to running several Claude Code sessions at once covers the worktree half of that, and why two agents in one directory quietly overwrite each other.

Set up Claude Code inside tmux

Claude Code starts in a pane without anything installed or configured. What changes is how the keyboard and the terminal behave: Shift+Enter submits your message instead of adding a line to it, and desktop notifications and the progress bar never reach the terminal you are actually looking at. Anthropic publishes a four-line block that fixes both, and one of the lines is there for mods that draw images.

1. Start a named session. Run tmux new -s with the name you want, such as fix-auth, so the window can be found again after it closes.
2. Add the settings Claude Code needs. Put the four settings below into ~/.tmux.conf.
3. Reload the config. Run tmux source-file ~/.tmux.conf so the running server picks the lines up without a restart.
4. Turn mouse mode on if you use fullscreen rendering. Add set -g mouse on, or the mouse wheel scrolls tmux instead of the conversation.
5. Start Claude Code in the pane and detach. Run claude where you want it, then leave with Ctrl+B d and come back with tmux attach -t and the session name.

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

The allow-passthrough line is what lets notifications and progress updates reach the outer terminal instead of being swallowed by tmux. The two extended-keys lines are what let tmux tell Shift+Enter apart from plain Enter, which is the whole reason the newline shortcut works afterwards. focus-events is not for either of those: Anthropic names it, with allow-passthrough, as what a mod's image needs to draw inside tmux.

The block has a floor. extended-keys and terminal-features arrived in tmux 3.2 and allow-passthrough in 3.3, so it wants tmux 3.3 or later.

Two details that catch people. Anthropic's step after adding the lines is to detach from tmux, attach again and restart Claude Code, and there is no shortcut past it. And run /terminal-setup in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal's own configuration file.

What breaks first, and how to fix it

Each row below is one symptom with its documented cause and its documented fix, and the source for each is listed at the foot of the page.

The Ctrl+B row is the one worth understanding rather than memorising. tmux sends every key you type to the program in the active pane, except when you press its prefix key first, which is Ctrl+B by default. Claude Code uses Ctrl+B to move a Bash command or an agent to the background. So tmux holds the keystroke, waits for the key that tells it which tmux command to run, and Claude Code never sees anything. Pressing Ctrl+B twice sends the key itself through to the program, which is exactly what Anthropic's documentation says to do.

Scrolling, scrollback and the alternate screen

tmux keeps a history buffer for every window. The default is 2000 lines, and the history-limit option changes it. To read back through it, press Ctrl+B [ to enter copy mode, and Ctrl+B ] to paste the most recent buffer. In copy mode a small indicator in the top-right corner of the pane shows where you are and how many lines of history there are, so you can tell whether you have reached the start of what tmux kept.

Where the conversation actually lives

Claude Code's fullscreen renderer keeps the conversation in the terminal's alternate screen buffer, not in the scrollback. That is why the terminal's own find and tmux's search cannot see it. Anthropic's way to hand it back is Ctrl+o for transcript mode, then [, which writes the whole conversation into the native scrollback with tool output expanded. From there it is ordinary text, and tmux copy mode can search and select it. Long sessions may pause for a moment while that happens, and the text stays put until you leave transcript mode with Esc or q.

The classic renderer is the other way round: it keeps the conversation in your terminal's native scrollback, so Cmd+F and tmux copy mode work as they always did. /tui default switches back to it if the alternate screen is costing you more than it gives. Anthropic fixed a redraw that duplicated scrollback lines in that renderer on tmux, so if you see duplicated blocks, check that you are on 2.1.121 or later.

Copy mode freezes the output in a pane while you read, so a session that is printing will appear to stop. It has not stopped. q leaves copy mode and the pane resumes.

Driving another pane with send-keys

The command is smaller than the results suggest. tmux send-keys sends a key, or several, to a target pane. Each argument is a key name such as C-c or NPage, and an argument tmux does not recognise as a key name is sent as a series of characters instead. Everything on the line is sent in order, first to last.

The flag that matters for text is -l. It turns key-name lookup off and sends the argument as literal characters. Lookup runs over the whole argument, so without -l any argument that is exactly a key name, such as Enter, Escape or Up, is sent as that key rather than as the word. A quoted sentence is one argument and survives either way, which is why the example below quotes the text and lists Enter as its own separate argument. -l is what sends a word that happens to be a key name as text.

Sending a prompt is two steps with a look in between, and the look is what capture-pane is for. Start the session and Claude Code first:

$ tmux new -d -s fix-auth -c ~/src/app
$ tmux send-keys -t fix-auth -l 'claude'
$ tmux send-keys -t fix-auth Enter
$ tmux capture-pane -pt fix-auth

That last line is a check, not a wait. capture-pane -p returns at once with a snapshot of the pane, so run it by hand and run it again until Claude Code's prompt is showing, then send the rest. In a folder you have not run Claude in before, the first thing in that pane is a trust dialog rather than a prompt. No output is shown for it here because what it prints depends on the session, and this page has no terminal capture behind it. On the first line, -d keeps the new session from attaching to this terminal and -c sets the directory it starts in.

Once the prompt is there, the prompt goes in the same way the command did:

$ tmux send-keys -t fix-auth -l 'Run the auth tests and fix the one failure.'
$ tmux send-keys -t fix-auth Enter

That is the limit of the technique. -t delivers to the pane you name, and nothing in tmux asks whether the program in that pane is ready, so a line can arrive while the answer to the last one is still being written. Anthropic has fixed a bug in that shape: keystrokes typed while a teammate was spawning leaked into the new tmux pane instead of reaching the leader's prompt. If you are scripting several panes, send one step, wait for the output you expect, then send the next.

Listing sessions from a script

Claude Code can list its own live sessions as JSON, with claude agents --json. Anthropic ships it for exactly this kind of scripting and names tmux-resurrect, status bars and session pickers as the uses. A status bar built on it can show what each session is doing, which a row of panes cannot.

Claude Code's own tmux support

Claude Code has its own tmux support, and it does not need you to write a layout by hand. --tmux creates a tmux session for a worktree, requires --worktree, and uses iTerm2's native panes when it can. --tmux=classic asks for traditional tmux instead.

Agent teams take it further, once you turn them on: Anthropic ships them experimental and disabled, and a team is only set up at session start when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set to 1 in your environment or settings.json. With that on, split-pane mode gives each teammate its own pane, so you can watch all of them at once and click into one to talk to it. The default display mode is in-process, where everything stays in your own terminal. Setting auto turns split panes on when you are already inside tmux, tmux lets Claude Code decide between tmux and iTerm2, and iterm2 needs the it2 CLI installed. The --teammate-mode flag sets it per session, and Anthropic labels that flag experimental: it does not appear in claude --help.

Two things to know before you build a workflow on panes. Split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal or Ghostty, so those terminals get the in-process view only. And Anthropic's own note on tmux is careful rather than enthusiastic: it has known limitations on certain operating systems and traditionally works best on macOS, and tmux -CC inside iTerm2 is the entrypoint Anthropic suggests.

When a team is finished, a tmux session can outlive the session that made it. Anthropic's step is tmux ls to find it and tmux kill-session -t with the name to end it. Anthropic has also fixed a failure where subagent spawning stopped working for good after tmux windows were killed or renumbered during a long run, which is one more reason to clean panes up deliberately rather than killing them out from under a working session.

Where the panes stop scaling

A pane is a rectangle of terminal output. That is all it is. Nothing in it distinguishes a session that is thinking from one that has been retrying the same failing command for twenty minutes, unless the text on screen happens to say so, and the text of a session that is busy retrying looks busy.

Two limits follow from the design. A row of panes has no summary: what you know is what you can see, and seeing it means looking at each pane in turn. And each pane's scrollback is bounded, so the earliest part of a long run falls off the top unless you raised the limit before you started.

None of that makes tmux the wrong tool. When the only thing in front of you is a terminal on a remote machine, a multiplexer is what keeps the work alive, and a session that survives the connection dropping is worth more than any dashboard.

Once several panes are running, the problem changes from doing the work to finding out what the work is doing. That is a reading problem, and it is where the next section starts.

Where a dashboard fits, and where tmux still wins

Omniscio is the desktop app we make for running Claude Code sessions, and it is built for the problem in the section above: several sessions are easy to start and hard to keep track of.

The left rail lists your projects with their live sessions beside them as coloured status dots, and each project carries a badge counting the sessions that need you, so "which one is waiting on me" is a glance rather than a tour of panes. A session also shows what it has cost in its own header, with token and turn totals one click away.

Isolation is the piece that replaces the worktree habit. It is off by default, and you can switch it on three ways: for one session from the ⋯ menu of a session that has not started yet, as Worktree Session, or by shift-clicking the + button in the Sessions panel; for a project under Edit Project → More options → Isolate new sessions; or app-wide in Settings → Sessions → Work on separate copies. It applies when a session starts and never retroactively, so a session already running keeps running where it is.

One exception is worth knowing if you drive several harnesses. On an engine that auto-approves every tool call, sessions are isolated by default in a git repository, because the worktree is what stands between the agent and your real checkout. The project and app-wide defaults cannot turn that off; an explicit per-session choice still can.

The honest other half: Omniscio is a desktop app, so it needs a machine to run on. If the only thing in front of you is a terminal over SSH, with no desktop anywhere, tmux is the tool and none of this changes.

A remote machine is not out of reach, though. SSH Remote runs one session's Claude CLI on another machine, such as a GPU box, a Linux dev server or a cloud VM, while you drive it from the Omniscio window on your desktop. So the remote case tmux covers often has an alternative in the app. One difference is worth knowing before you swap one for the other: keeping a remote session going while your own computer sleeps is off until you switch it on, and it is for your own Linux remotes only, under Settings → SSH Remotes → Keep sessions working while this computer sleeps.

The features page lists the rest of what the app does and the download page has the installers. For the wider picture, running several Claude Code sessions at once covers worktrees, quota and cost, the parallel agents guide covers Claude Code's own parallel options, the agent dashboard guide covers what to look at when the number of sessions grows, and the cost calculator prices a fleet before you start one.

Sources

Every Anthropic and tmux fact on this page rests on one of these, and the date beside each one is the day we read it. The Omniscio section rests on our own documentation and the defaults in the app, and the rows in the fact ledger beside this page name the file for each claim.

• Configure your terminal for Claude Code, for the ~/.tmux.conf block, what each line restores, the reload and reattach steps, /terminal-setup, and the session-status caveat inside tmux. Read October 25, 2026.
• Fullscreen rendering, for the three tmux caveats, mouse mode, the tmux -CC incompatibility, synchronized output, and the alternate screen buffer. Read October 25, 2026.
• Interactive mode, for Ctrl+B pressing twice, transcript mode, the [ key that writes to scrollback, and FORCE_HYPERLINK. Read October 25, 2026.
• CLI reference, for --tmux, --tmux=classic and --teammate-mode. Read October 25, 2026.
• Agent teams, for the display modes, the split-pane requirements, Anthropic's note on tmux support, the unsupported terminals, and cleaning up an orphaned session. Read October 25, 2026.
• Claude Code changelog, current version 2.1.310, released October 23, 2026, and the version notes quoted on this page: 2.1.78, 2.1.92, 2.1.121, 2.1.145, 2.1.183, 2.1.200 and 2.1.212. Read October 25, 2026.
• Permissions, for the workspace trust dialog Claude Code shows in an interactive session, which is what appears in the pane the first time it runs in a folder. Read October 25, 2026.
• tmux: Getting started, for sessions, windows and panes, the prefix key, attaching and detaching, listing sessions, splitting a window, copy mode, buffers and the mouse option. Read October 25, 2026.
• tmux manual, for new-session and its -d and -c flags, send-keys and -l, the history-limit option, and the default of 2000 lines of history. Read October 25, 2026.
• tmux changelog, for which release added extended-keys, terminal-features and allow-passthrough, which is what dates the config block. Read October 25, 2026.
• tmux releases, for the current release, 3.8, published September 9, 2026. Read October 25, 2026.

tmux supports only its latest release, and makes one about every six months, so a fix that depends on the newest version is only a fix if you are on it. Anthropic's documentation carries the same moving target: several of the behaviours above changed in a numbered release, and the changelog is the record of which.

Common questions

Why does Ctrl+B not background a task inside tmux?

Ctrl+B is tmux's own prefix key, so tmux takes the keystroke before Claude Code sees it. Anthropic's answer is to press it twice: the second press is passed through to the program in the active pane.

Does Claude Code work in tmux with no configuration?

It runs, and three things behave differently. Shift+Enter submits instead of inserting a newline, and desktop notifications and the progress bar never reach the terminal you are looking at. Anthropic publishes a four-line config block that restores them.

How do I scroll up through a Claude Code conversation in tmux?

Turn on mouse mode with set -g mouse on, and the wheel scrolls the conversation. PgUp and PgDn work whether mouse mode is on or not. With fullscreen rendering the conversation sits in the alternate screen buffer, so the terminal's own find and tmux copy mode cannot see it until you press Ctrl+o and then [ to write it into the scrollback.

Can I drive another Claude Code session with tmux send-keys?

Yes. tmux send-keys sends a key or a string to a named pane, and the -l flag sends text literally so a sentence is not read as key names. What it cannot do is tell you whether the session in that pane is ready to receive the text.

Does Claude Code have its own tmux option?

It has --tmux, which creates a tmux session for a worktree and requires --worktree. Agent teams have a split-pane mode too, where each teammate gets its own pane and tmux or iTerm2 is required, and they are experimental and off by default until CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is 1.

How many lines of Claude Code output does tmux keep?

Two thousand per window by default, which is tmux's own default for the history-limit option. Raise it in ~/.tmux.conf if a long session scrolls past the start of what you need.