Setting up a parallel agent fleet on macOS (5+ sessions, no chaos)

Running five Claude Code sessions in parallel on a single Mac is a real workflow once you stop alt-tabbing through terminal windows. The trick is structure — directory layout, multiplexer, file manager, prompt library — set up once, used daily.

What "fleet" means here

A fleet is 3-5 AI sessions running simultaneously, each on a distinct task:

• Session 1: rewriting auth in main app.
• Session 2: drafting next week's launch post.
• Session 3: porting iOS module to AppKit.
• Session 4: bisecting a perf regression.
• Session 5: synthesis from 12 papers.

Each session has its own working directory, its own goal, its own AI context. They don't talk to each other; you orchestrate.

The five components

1. Terminal multiplexer — cmux

cmux is the multiplexer purpose-built for agent sessions. tmux works too. The point: one terminal window with named tabs/panes, each running one agent.

brew install cmux
cmux create rewrite-auth-main --dir ~/dev/sessions/2026-04-22-auth-rewrite/repo
cmux create draft-launch-post --dir ~/dev/sessions/2026-04-22-launch-post
# ...
cmux list

Each session has a name and working directory. cmux switch <name> jumps to a session. cmux list shows status.

2. File manager — mq-dir

mq-dir's quad-pane layout is the visual orchestration layer. Each pane shows one session's directory. You see what 4 agents are producing simultaneously.

brew install --cask mq-dir

mq-dir's sidebar has a CMUX section that mirrors cmux list — click a session to focus its directory in the focused pane.

3. Session directory layout

Each session is a directory under ~/dev/sessions/:

~/dev/sessions/
├── 2026-04-22-auth-rewrite/
│   ├── CLAUDE.md            ← scope, goal, constraints
│   ├── notes.md             ← running log
│   ├── artifacts/           ← screenshots, transcripts
│   └── repo/                ← worktree of the actual codebase
└── 2026-04-22-launch-post/
    └── ...

The session directory is ephemeral; commits go into repo/ which lives elsewhere. See the project layout post for the full structure.

4. Prompt library

A flat directory of reusable prompts:

~/dev/_shared/prompts/
├── review/code-review-strict.md
├── generate/test-from-fn.md
└── ...

Reference these in session CLAUDE.md files instead of inlining. See the prompt library post for the full layout.

5. The CLAUDE.md per session

Two paragraphs declaring goal + scope + constraints:

# Session: auth rewrite — 2026-04-22

## Goal
Replace legacy CookieAuth with JwtAuth.

## Out of scope
Don't touch user-management UI.

## Constraints
- TypeScript strict
- npm test before each commit
- PR to feat/auth-jwt

The agent reads this on session start. You point at it when the agent drifts.

Setup walkthrough

Step 1: directory structure

mkdir -p ~/dev/sessions ~/dev/repos ~/dev/_shared/prompts

Step 2: install tools

brew install cmux
brew install --cask mq-dir

Step 3: prep prompt library

Move your existing prompts (Notion, snippets, whatever) into ~/dev/_shared/prompts/ as flat .md files. Aim for 10-20 to start.

Step 4: configure mq-dir

Open mq-dir, hit ⌥⌘4 for quad-pane layout. Add ~/dev/sessions/, ~/dev/repos/, ~/dev/_shared/, and ~/Downloads/ (or whatever your fourth context is) to favorites.

Save as a Project named "Fleet."

Step 5: spawn first session

mkdir -p ~/dev/sessions/2026-04-22-test-session/repo
cd ~/dev/sessions/2026-04-22-test-session
cat > CLAUDE.md <<EOF
# Session: test
## Goal
Just experimenting with the fleet workflow.
## Out of scope
Anything real.
## Constraints
None.
EOF

cmux create test-session --dir ~/dev/sessions/2026-04-22-test-session
cmux attach test-session
# inside the cmux pane:
claude-code
> Read CLAUDE.md and tell me what we're doing.

If this works, the foundation is in place. Add real sessions next.

Daily flow

A typical workday:

Morning startup

cmux list                    # check what's running from yesterday
cmux switch <session>        # attach to one

mq-dir auto-restores yesterday's "Fleet" project — same panes pinned to same session directories. You're back where you left off.

During work

• mq-dir's CMUX sidebar shows session statuses.
• ⌘1-4 cycles focus through the 4 panes (4 sessions visible).
• When a session needs review, click its sidebar row to bring focus.

Adding a new session

mkdir -p ~/dev/sessions/2026-04-22-new-task/repo
cd ~/dev/sessions/2026-04-22-new-task
# write CLAUDE.md
cmux create new-task --dir $PWD
cmux attach new-task
claude-code

In mq-dir, drag the new session directory into one of the 4 panes (or use the CMUX sidebar to jump there).

End of day

cmux list           # what's still running?

For sessions that finished: review the artifacts in mq-dir, commit any work, then cmux kill <session> and rm -rf ~/dev/sessions/<session>/.

For sessions still running: leave them. They survive overnight.

Common gotchas

Two sessions touching the same repo

Bad. They'll fight on git status and possibly clobber each other.

Fix: each session uses a git worktree, not a clone:

cd ~/dev/repos/main-app
git worktree add ~/dev/sessions/2026-04-22-auth-rewrite/repo feat/auth-jwt

Now the session has its own working tree on its own branch. Multiple sessions can have worktrees of the same repo without conflicts.

Forgetting which session is which

Use cmux's named sessions. claude-1 through claude-8 is unmaintainable; rewrite-auth-main is scannable.

Prompts decay

The prompt library is the highest-leverage asset. Maintain it: when you fix a prompt, save it back. When you find yourself typing the same instruction twice, extract it.

Artifact buildup

Each session's artifacts/ fills up over weeks. Quarterly cleanup: rm -rf ~/dev/sessions/<old quarter>-*. Brutal but necessary.

Agents producing into the wrong pane

If you cd inside a cmux pane, the agent thinks that's the working directory. Stay disciplined about not navigating during a session.

Memory pressure

Five Claude Code sessions + mq-dir + your editor + browser can hit 8GB+. On a 16GB Mac you're fine; on 8GB you'll feel it. M-series memory bandwidth helps, but don't push beyond your hardware.

Variations

Smaller fleet (2-3 sessions)

Don't need the full setup. Just:

• 2H mq-dir layout (two panes side-by-side).
• 2-3 cmux sessions.
• Skip Projects (one workspace is enough).

Larger fleet (6-8 sessions)

Push the limit. Two options:

• Keep 4 visible in mq-dir, rotate which 4 via Projects (Project A = sessions 1-4, Project B = sessions 5-8).
• Distribute to a second machine. SSH the first agent to that box; mq-dir on local stays the orchestrator.

Distributed fleet (mixed local + remote)

Some agents on local Mac, some on a beefy Linux box via SSH. cmux works locally; for remote use tmux -CC or a separate cmux instance per machine. mq-dir doesn't see remote (local-first), but Forklift or terminal SSH covers remote file viewing.

What this saves you

After running this setup for months, the compound saving:

• Context-switch time: drops from ~30s per switch to ~3s.
• "Where was I" recovery: drops from minutes to immediate.
• Lost artifacts: drops to zero.
• Prompt library quality: compounds — gets better every week.

The setup cost is one afternoon. The payoff is daily for years.

Verdict

Five parallel agents is feasible on a single modern Mac with the right tooling. The bottleneck is workflow structure, not AI capability.

The canonical stack:

• cmux — sessions.
• mq-dir — navigation and visual orchestration.
• Flat prompt library — ~/dev/_shared/prompts/.
• Session directories — ~/dev/sessions/<date>-<topic>/.
• CLAUDE.md per session — goal, scope, constraints.

All free, all open-source, all native to macOS.

If you're running 3+ agents and feeling the chaos, this stack pays back within a week.