Using tmux with Claude Code

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. 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 STDIN[^1]. 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.