cmux multi-session setup: running 5 AI agents in parallel without losing your mind

You launch one Claude Code session. It's working. You start another. Now you have two terminals. You start a third. Now you alt-tab between them. By the fifth, you've forgotten which session was on the auth refactor and which was on the docs port.

A multiplexer fixes the alt-tab problem. cmux fixes the naming problem on top of that.

What cmux does that tmux doesn't

tmux is a Swiss Army knife — windows, panes, sessions, copy mode, status bar. cmux is opinionated:

• Each session has a name and a working directory (not just a label)
• Sessions have a status: idle, running, needs-review
• The session list is a first-class UI, not a status-bar string
• Lifecycle hooks: when a session enters needs-review, run a notification

This shifts the cognitive model. With tmux you have windows; with cmux you have agents on tasks.

Install

brew install cmux            # if your local tap has it
# or
curl -fsSL https://cmux.sh/install | sh

Verify:

cmux --version
cmux list           # empty

Naming convention

The single highest-leverage habit:

cmux create <verb>-<noun>-<scope> --dir <working-directory>

Examples:

cmux create rewrite-auth-main --dir ~/dev/repos/main-app
cmux create draft-launch-post --dir ~/dev/sessions/2026-04-25-launch-post
cmux create port-ios-appkit --dir ~/dev/repos/mq-dir
cmux create bisect-perf-regression --dir ~/dev/repos/api-server

Three parts:

1. Verb (rewrite, draft, port, bisect) — what you're doing.
2. Noun (auth, launch-post) — what it's about.
3. Scope (main, appkit) — which target.

You can scan a list of 8 sessions and instantly know what each one is. Without this convention you get claude-1 through claude-8 and you're back to alt-tab archaeology.

Launching agents inside cmux

Inside the session, run the agent normally:

# Inside session 'rewrite-auth-main'
$ claude-code
> Read CLAUDE.md and start the auth rewrite as scoped.

cmux watches stdout. When the agent prints a recognizable "I need input" prompt (or you Ctrl+C to pause), the session flips to needs-review. cmux can post a system notification or play a sound — useful when you have 5 sessions and one finishes.

Tour of common cmux commands

cmux list                          # all sessions
cmux attach rewrite-auth-main      # jump into one
cmux switch rewrite-auth-main      # same; quicker
cmux kill draft-launch-post        # end + cleanup
cmux rename old-name new-name      # if naming was off
cmux pwd rewrite-auth-main         # print working directory
cmux status                        # tabular: name | dir | status | pid

A useful alias:

alias cml="cmux list"
alias cma="cmux attach"

File-manager integration

This is where mq-dir becomes specifically useful. mq-dir's sidebar has a CMUX section that mirrors cmux list:

SIDEBAR
├── Favorites
│   ├── Desktop
│   ├── Downloads
│   └── …
├── Projects
└── CMUX
    ├── ▶ rewrite-auth-main
    ├── ✓ draft-launch-post
    └── ▶ port-ios-appkit

Click a session row → opens the working directory in the focused pane. ⌘-click → opens it as a new tab. The file manager becomes the navigator for your agent fleet.

The ▶ (running) / ✓ (needs review) status comes from cmux's status API. When an agent finishes, the icon changes and you know to attach.

Failure modes to avoid

After running 5+ parallel sessions for a few months, four mistakes recur:

1. Sessions outliving their purpose. The agent finished hours ago, you're still attaching to a dead session. Set a kill-on-idle timeout, or just cmux gc weekly.
2. Working directories that overlap. Two agents both rooted at the same repo will fight on git status. Use worktrees for each session.
3. Agent prompt-induced divergence. Two sessions, both told to refactor auth, drift apart. Use scoped CLAUDE.md files per session to constrain.
4. Ambient terminal noise. cmux session captures everything; if a build process inside leaks ANSI, output gets garbled. Pipe through cat or --no-color flags.

A typical day's session list

After a month of cmux, your cmux list looks like:

NAME                          DIR                                        STATUS
rewrite-auth-main             ~/dev/sessions/2026-04-22-auth-rewrite/    needs-review
draft-launch-post             ~/dev/sessions/2026-04-22-launch-post/     running
port-ios-appkit               ~/dev/repos/mq-dir/                        idle
bisect-perf-regression        ~/dev/repos/api-server/                    needs-review
research-cache-papers         ~/dev/sessions/2026-04-23-cache-research/  running

Five sessions. None of them confused with another. Each agent has a clear scope, a clear working directory, a clear status.

The multiplier with mq-dir

The pattern that closes the loop:

1. cmux runs the agent processes.
2. mq-dir mirrors the session list in its sidebar.
3. Click a session in the sidebar → focused pane jumps to its working directory.
4. The pane shows you exactly what the agent has done so far (file list, modification times).
5. ⌘-click opens it as a new tab — keep the previous context, watch the new one.

You stop alt-tabbing. The fleet has a navigator. Sessions stop melting into each other.

When you don't need this

Two cases:

• You only run one agent at a time. Then plain terminal is fine; tmux is fine. cmux is for parallelism.
• You don't separate sessions by task. If all your sessions are "general help on this repo", names don't matter, and cmux's value collapses.

For everyone running parallel agents on distinct tasks, cmux + mq-dir is the closest thing to a flight-deck control panel that exists in 2026 for AI dev work. Both free, both small.