{
  "$type": "site.standard.document",
  "description": "How I run Claude Code inside tmux, including the tmux config for Shift+Enter, notifications, fullscreen mode, scrolling, search, and multiple agent sessions.",
  "path": "/using-tmux-with-claude-code/",
  "publishedAt": "2025-11-28T14:17:00.000Z",
  "site": "at://did:plc:bryys25pc2fnagnyxqgsglhd/site.standard.publication/3mn26bjkkmh23",
  "tags": [
    "Tools",
    "AI"
  ],
  "textContent": "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.\n\nMy setup is simple: regular tmux, a few Claude Code tmux settings, and tmux handling the terminal things Claude Code doesn't need to reinvent.\n\nMy prefix is ctrl-w, so replace that with your own prefix if you use the default ctrl-b.\n\nCONFIGURE TMUX FOR CLAUDE CODE\n\nClaude Code works inside tmux without much setup, but a few things behave better with the right tmux config.\n\nAdd this to ~/.tmux.conf:\n\nset -g allow-passthrough on\nset -s extended-keys on\nset -as terminal-features 'xterm*:extkeys'\n\nThen reload tmux:\n\ntmux source-file ~/.tmux.conf\n\nThe Claude Code terminal config docs recommend these settings for two things I care about:\n\n * Shift+Enter can be distinguished from plain Enter, so it can insert a newline instead of submitting the prompt\n * desktop notifications and progress updates can pass through tmux to the outer terminal\n\nIf 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.\n\nUSE NORMAL TMUX, NOT ITERM2 TMUX INTEGRATION\n\nI use regular tmux inside my terminal.\n\nDon'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.\n\nRegular tmux in iTerm2 is fine.\n\nFULLSCREEN RENDERING IN TMUX\n\nClaude Code has fullscreen rendering now. You can enable it inside Claude Code with:\n\n/tui fullscreen\n\nIf you want mouse wheel scrolling inside Claude Code's fullscreen UI, enable tmux mouse mode:\n\nset -g mouse on\n\nThen reload:\n\ntmux source-file ~/.tmux.conf\n\nI 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.\n\nCLAUDE CODE DOESN'T NEED MORE FEATURES\n\nI 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.\n\nThis applies to other LLM CLI tools too.\n\nSCROLL CLAUDE CODE OUTPUT WITH TMUX COPY MODE\n\nIn tmux, ctrl-w [ enters copy mode. From there:\n\n * ctrl-u / ctrl-d — page up/down\n * j / k — line by line\n * / — search forward\n * ? — search backward\n * n / N — next/previous match\n * ctrl-c — exit copy mode\n\nThat's your pagination and search right there.\n\nCAPTURE THE CLAUDE CODE BUFFER TO AN EDITOR\n\nThis lets you copy the entire tmux buffer (aka contents) to your editor:\n\ntmux capture-pane -t 0 -p -S -10000|v\n\nv is my script to trigger Neovim to read STDIN[^1]. The flags:\n\n * -t 0 — target pane 0\n * -p — print to stdout (instead of to a tmux buffer)\n * -S -10000 — capture 10000 lines back\n\nUseful for grabbing logs, script output, or the output from a Claude Code session.\n\nPASS CTRL SHORTCUTS THROUGH TMUX\n\nCoding 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.\n\nThe fix is to bind a passthrough in tmux:\n\nbind o send-keys C-o\n\nNow ctrl-w then o sends ctrl-o directly to the program running in the pane.\n\nRUN MULTIPLE CLAUDE CODE SESSIONS IN TMUX\n\nI 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.\n\nI 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.\n\nThis 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.\n\nCLAUDE CODE UNDERSTANDS TMUX\n\n(Note that in tmux terminology, \"windows\" are really what most people would call tabs.)\n\nClaude 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.\n\nYou 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.\n\nFor 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.\n\nThe 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).\n\nIf you're interested, check out my complete agentic coding setup and tech stack.\n\n[^1]: v does a few other things with Neovim like opening a file by filename, but that's not relevant here.",
  "title": "Using tmux with Claude Code",
  "updatedAt": "2026-05-11T00:00:00.000Z"
}