# How to run Claude Code in tmux on a Mac

> Claude Code tmux setup for a Mac: the config lines it needs, mouse scrolling, notifications, agent team panes, and when claude --bg replaces tmux.

Published 2026-11-03 on the Starkomand blog: https://starkomand.com/blog/claude-code-tmux/

Running Claude Code in tmux gets you two things: the session keeps going after you close the terminal, and you can see several sessions in one window. It also breaks a few things until you configure it. Shift+Enter submits instead of adding a line, and desktop notifications never reach your Mac.

The settings below come from Anthropic's [terminal](https://code.claude.com/docs/en/terminal-config), [fullscreen](https://code.claude.com/docs/en/fullscreen) and [agent teams](https://code.claude.com/docs/en/agent-teams) docs, read on 3 November 2026. I ran the config in this post on tmux 3.8 with Claude Code 2.1.317, read the values back, and confirmed that Shift+Enter adds a line through tmux. I did not test notifications through it. I build Starkomand, a Mac app for running coding agents on one canvas, and the last section says where it replaces tmux and where it does not.

## How do I run Claude Code in tmux?

Install tmux, start a named session, and run Claude Code inside it:

```
brew install tmux
tmux new -s claude
cd ~/Projects/my-app
claude
```

Press Ctrl-b, then d, to detach. Claude keeps working and you get your shell back. You can close the terminal at this point. To come back:

```
tmux ls
tmux attach -t claude
```

Inside a session, Ctrl-b c opens a new window and Ctrl-b % splits the current one, so a second agent is two keystrokes away.

![A tmux session split into three panes. Claude Code on the left answers a two-line question about the git history, the dev server on the top right reads storefront ready on port 3000, and git log runs on the bottom right. The tmux status bar runs along the bottom.](https://starkomand.com/assets/blog/claude-code-tmux/tmux-panes.jpg)

*A real tmux 3.8 session with the config below, inside a Starkomand window on a demo project. The second line of the Claude Code prompt was typed with Shift+Enter.*

## What goes in .tmux.conf for Claude Code?

Add these lines to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply them to the running server:

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

`allow-passthrough` lets notifications and progress updates reach your outer terminal. The two `extended-keys` lines let tmux tell Shift+Enter from plain Enter. `mouse on` sends wheel events to Claude Code in the fullscreen renderer, and without it they go to tmux.

If you use `/terminal-setup`, run it in your host terminal, outside tmux, because it writes to that terminal's own config.

## Why does scrolling not work in tmux?

Claude Code has two renderers, and scrolling depends on which one you are in. Run `/tui` with no argument to see.

**Fullscreen** keeps the conversation on the alternate screen, the way `vim` does. tmux copy mode and search cannot see it. Scroll with the wheel, which needs `mouse on`, or with PgUp and PgDn, which work either way. On a MacBook keyboard, that is Fn+↑ and Fn+↓. To search with tmux tools, press Ctrl+o for transcript mode and then `[`, which writes the whole conversation into normal scrollback until you leave transcript mode.

**Classic** keeps everything in scrollback, so tmux copy mode works as usual. Switch with `/tui default`.

Two more things affect how it looks:

- **Flicker.** tmux releases through the 3.6 series do not implement synchronized output, so redraws can flicker. Upgrade tmux, or run Claude Code in its own tab outside tmux.
- **`tmux -CC`.** iTerm2's integration mode draws panes as native splits, and fullscreen rendering does not work there. The wheel does nothing, and double-click can corrupt the terminal state. Claude Code starts in the classic renderer in that mode, so leave it there. Plain tmux inside iTerm2 is fine.

## Why don't notifications arrive in tmux?

tmux swallows the escape sequences Claude Code uses unless `allow-passthrough` is on. With that line in place, a notification reaches your outer terminal, which still has to support it. Ghostty, Kitty and iTerm2 do, and iTerm2 needs its alerts turned on. In any other terminal, use [a notification hook](https://starkomand.com/blog/claude-code-notifications/), which runs a command directly and does not depend on tmux at all.

## How do agent team panes work in tmux?

Agent teams give each teammate its own Claude Code session, and in tmux each one gets its own pane. The feature is experimental and off by default. Add this to `~/.claude/settings.json`:

```json
{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
  "teammateMode": "auto"
}
```

Start Claude Code inside tmux and ask for a team in plain words: "Spawn three teammates to review PR #142, one each for security, performance and test coverage." Click a pane to talk to that teammate directly.

Three things are worth knowing first. Teams use significantly more tokens than a single session, since every teammate has its own context window. Two teammates editing one file will overwrite each other, so give each its own files. And if a session lingers afterwards, `tmux ls` finds it and `tmux kill-session -t <name>` ends it.

## Do you still need tmux to keep Claude Code running?

Often not. Claude Code now has [background sessions](https://code.claude.com/docs/en/agent-view), which keep running with no terminal attached:

```
claude --bg "investigate the flaky settings test"
claude agents
claude attach <id>
```

Inside a running session, `/bg` moves it to the background. A separate supervisor process runs these, so closing your shell does not stop them. They resume after the Mac sleeps, and a restart stops them, the same as tmux.

tmux is still the better tool in three cases: over SSH, where it protects you from a dropped connection; when you want to see several live panes at once; and with other CLIs such as Codex, which `claude --bg` does not cover. OpenAI's Codex config docs do not mention tmux, so I have no Codex setting to quote, but the session commands above work the same for any program.

Neither one keeps working with the lid closed. Closing a MacBook normally sleeps the whole machine, and `caffeinate -i` does not change that. Of the assertion it relies on, Apple's `IOPMLib.h` says: "The system may still sleep for lid close, Apple menu, low battery, or other sleep reasons."

## What does tmux not show you?

tmux can flag a window that rang a bell. It cannot tell you what the agent asked, so with several sessions you still go pane by pane. Starkomand takes the opposite approach. Each agent is a window on one canvas, and tapping **Space** turns them all over.

![Four agent windows turned over on the Starkomand canvas. Marcus and Diana read Finished, with each agent's last line. Felix reads Waiting on your answer in amber with the question "Should discount codes be stored in the database and validated when entered, or hardcoded in config?" Oscar reads Waiting on you, with approve Bash: npm install zod.](https://starkomand.com/assets/blog/claude-code-tmux/window-backs.jpg)

*Real Claude Code and Codex sessions on a demo project, turned over with a tap of Space. The titles are the agents' own names for each conversation.*

Here is how it lines up against the reasons people reach for tmux:

- **Closing the window.** A local server holds the sessions, so you can hide the canvas and agents keep working.
- **Quitting the app.** Run an agent as a persistent one through [Herdr](https://herdr.dev), set up in **Settings → Herdr**, and it outlives Starkomand.
- **Closing the lid.** **Settings → Lid closed → Keep agents working** keeps a MacBook awake while agents work, with the screen and keyboard dark. It asks for your password once.

A restart of the Mac ends live sessions here too. For agents on a remote server, tmux over SSH is still what I would use today. It is also free, and it works in any terminal, so for one or two sessions you may never need anything else.

## The Starkomand features in this walkthrough

- [Turn every window over to see where each agent stands](https://starkomand.com/#scene-glance-title).
- [Persistent agents and lid-closed work](https://starkomand.com/#features).
- [Claude Code, Codex and other CLI agents with your own sign-ins](https://starkomand.com/agents/).
- [Answers on keeping agents running when you leave](https://starkomand.com/#faq).

More walkthroughs: [the best terminal for Claude Code on a Mac](https://starkomand.com/blog/best-terminal-for-claude-code/), [Claude Code notifications](https://starkomand.com/blog/claude-code-notifications/), and [how to keep track of multiple agent sessions](https://starkomand.com/blog/resume-two-projects-with-agent-recaps/).

To try several agents on one canvas, [start the 3-day trial of Starkomand](https://starkomand.com/). It includes every feature, and your agents keep using the subscriptions you already have.