I run Claude Code inside tmux all day. I get persistent sessions, scrollback, search, multiple agent windows, and a place for dev servers to keep running while the coding agent works.

My setup is simple: regular tmux, a few Claude Code tmux settings, and tmux handling the terminal things Claude Code doesn’t need to reinvent.

My prefix is ctrl-w, so replace that with your own prefix if you use the default ctrl-b.

I also use Claude Code YOLO mode for small TODO-list work, but tmux is where I run interactive Claude Code sessions. The distinction matters: YOLO mode is about permissions and automation; tmux is about persistence, scrollback, and coordinating agent sessions.

Update: How I Use tmux in June 2026

I still use one main tmux session for most coding work. Each project or agent gets a window, and panes are addressed as main:3.0, main:3.1, and so on. In my shorthand, tmux 3.1 means session main, window 3, pane 1.

That convention matters because coding agents can act on it. I can tell an agent to check tmux 3.1 for backend logs, send a command to another pane, or inspect a long-running deploy without me pasting output back into the chat.

The current pattern:

  • interactive Claude Code, Droid, or Codex sessions each run in their own tmux window
  • dev servers stay in tmux, usually already running before the agent starts
  • finite long-running jobs run in tmux with a callback so the active agent session can verify when the command finishes
  • window names are auto-renamed from pane content, so the status bar shows hb post draft, blue fix auth, or wm refactor instead of five generic agent names

I wrote more about the full setup in my complete agentic coding setup and about the project instructions in how I write and maintain AGENTS.md.

Configure tmux for Claude Code

Claude Code works inside tmux without much setup, but a few things behave better with the right tmux config.

Add this to ~/.tmux.conf:

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

Then reload tmux:

tmux source-file ~/.tmux.conf

The Claude Code terminal config docs recommend these settings for two things I care about:

  • Shift+Enter can be distinguished from plain Enter, so it can insert a newline instead of submitting the prompt
  • desktop notifications and progress updates can pass through tmux to the outer terminal

If you run many long Claude Code sessions, those two details matter. I want the agent to notify me when it needs input, and I don’t want multiline prompts to be annoying.

Use Normal tmux, Not iTerm2 tmux Integration

I use regular tmux inside my terminal.

Don’t use iTerm2’s tmux -CC integration mode with Claude Code fullscreen rendering. Claude Code’s fullscreen docs call out that integration mode breaks the alternate screen buffer and mouse tracking in ways that make scrolling and selection unreliable.

Regular tmux in iTerm2 is fine.

Fullscreen Rendering in tmux

Claude Code has fullscreen rendering now. You can enable it inside Claude Code with:

/tui fullscreen

If you want mouse wheel scrolling inside Claude Code’s fullscreen UI, enable tmux mouse mode:

set -g mouse on

Then reload:

tmux source-file ~/.tmux.conf

I don’t rely on the mouse much. I still prefer tmux copy mode for inspecting older output because it works the same way across Claude Code, Droid, Codex, shell commands, dev servers, and logs.

Claude Code Doesn’t Need More Features

I saw someone on GitHub requesting pagination functionality for Claude Code. You don’t need it. If you run Claude Code in tmux, you already have scrolling, paging, and search.

This applies to other LLM CLI tools too.

Scroll Claude Code Output with tmux Copy Mode

In tmux, ctrl-w [ enters copy mode. From there:

  • ctrl-u / ctrl-d — page up/down
  • j / k — line by line
  • / — search forward
  • ? — search backward
  • n / N — next/previous match
  • ctrl-c — exit copy mode

That’s your pagination and search right there.

Capture the Claude Code Buffer to an Editor

This lets you copy the entire tmux buffer (aka contents) to your editor:

tmux capture-pane -t 0 -p -S -10000|v

v is my script to trigger Neovim to read STDIN1. The flags:

  • -t 0 — target pane 0
  • -p — print to stdout (instead of to a tmux buffer)
  • -S -10000 — capture 10000 lines back

Useful for grabbing logs, script output, or the output from a Claude Code session.

Pass Ctrl Shortcuts Through tmux

Coding agents like Droid and Claude Code use ctrl shortcuts — for example, ctrl-o expands details and transcripts. Since tmux intercepts ctrl shortcuts, and I had already mapped ctrl-o to switch to the last tmux window, pressing ctrl-o would never reach the coding agent.

The fix is to bind a passthrough in tmux:

bind o send-keys C-o

Now ctrl-w then o sends ctrl-o directly to the program running in the pane.

Run Multiple Claude Code Sessions in tmux

I routinely run 3-5 coding agent sessions in parallel — each in its own tmux window. One agent implements a feature, another writes tests, a third fixes lint warnings on a different project. This is natural with terminal agents — each is just a process in a window.

I auto-rename the tmux windows so my status bar shows hb post draft, blue fix auth, wm refactor instead of five windows all named “droid”. At a glance I know what each agent is working on.

This is why I use tmux instead of Warp — tmux is the glue that lets me coordinate agents across sessions without being locked into any particular terminal.

Claude Code Understands tmux

(Note that in tmux terminology, “windows” are really what most people would call tabs.)

Claude Code understands tmux. If you mention “tmux 9.0”, it’ll know it’s referring to the current session’s 0th pane in the 9th window (though I found it’s helpful to mention you always use one session, if you do, in CLAUDE.md/AGENTS.md). It knows the tmux subcommands to read the pane’s contents, scroll back, issue command, or re-run a command from history.

You can also run a coding agent session in a separate tmux window and have your main coding agent coordinate with it — send it tasks, check its output, or let it work independently on a parallel track. I wrote about auto-renaming tmux windows for AI coding agents so you can tell them apart at a glance.

For example, I have my backend API server running in a tmux window with live reload. When I ask Claude Code to make changes, I can tell it to look at the server output in that window+pane. It can see the errors as they happen and fix them while iterating on a feature.

The difference from using Claude Code’s Bash tool is that I can easily see the full output myself and intervene when needed. It’s more interactive (if I want to).

If you’re interested, check out my complete agentic coding setup and tech stack.

  1. v does a few other things with Neovim like opening a file by filename, but that’s not relevant here. ↩