Running Multiple Claude Code Agents in Parallel: A Practical macOS Workflow
One coding agent is a tool. Five coding agents running at once is a workflow problem. Once you start dispatching Claude Code sessions to separate branches — one refactoring the API layer, one writing tests, one chasing a flaky CI job — the bottleneck stops being the model and becomes you: your ability to context-switch, keep track of which window owns which task, and notice when an agent has quietly stalled waiting for a permission prompt.
This guide covers the concrete mechanics of parallel agent operation on macOS: how to isolate sessions so they don’t collide, how to name and arrange windows so Cmd+Tab becomes navigation instead of roulette, and the habits that keep five agents from becoming five half-finished branches.
Why Parallelism Beats a Single Long Session
A single agent session degrades as the context window fills. It re-reads files it already read, loses track of earlier decisions, and starts producing edits that contradict work from twenty turns ago. Splitting work across sessions is not just about speed — it’s about keeping each context window small and focused.
The right unit of parallelism is a task with a clean boundary:
- Independent files or modules. Two agents editing
auth/andbilling/will never conflict. - Investigation vs. implementation. One agent reads and reports; another writes code based on the report.
- Long-running vs. interactive. A test suite run or a large migration can sit in its own window while you actively converse with another session.
The wrong unit is two agents editing the same file. Git will not save you from an agent that overwrites a change it never saw.
Isolation: Git Worktrees Are the Foundation
The single highest-leverage habit is giving every agent its own working directory. Git worktrees do this natively — same repository, separate checkouts, separate branches, zero copying of .git history:
git worktree add ../proj-auth feature/auth-refactorgit worktree add ../proj-tests feature/test-coveragegit worktree add ../proj-ci fix/flaky-pipeline
Each agent starts in its own directory. No agent can stomp another’s uncommitted work, and git worktree list gives you an instant map of what’s in flight. When a branch is merged, git worktree remove cleans it up.
The one gotcha: dependencies. Node’s node_modules, Python virtualenvs, and build caches are per-directory. Budget the disk space, or symlink shared caches where your toolchain supports it. On a machine juggling several worktrees plus containers, an external SSD stops being a luxury — a fast USB-C external SSD on Amazon Japan → handles overflow build artifacts without touching your internal drive.
Session Management: Naming, Resuming, Logging
Give every session a name you’ll recognize at 4pm
Agent sessions are resumable, but only if you can identify them. Claude Code stores session history per project directory, and claude --resume lets you pick a prior conversation. That picker is only useful when the sessions are distinguishable — which is another argument for one worktree per task, since the directory name becomes the label.
Rename your terminal tabs to match. In iTerm2, Cmd+I opens the session settings where you can set a tab title; in Terminal.app, Cmd+Shift+I does the equivalent. Thirty seconds of naming saves an hour of “which window was the migration in?”
Log everything an agent does unattended
Any agent you’re not actively watching should write to a log file. Piping output through tee into a timestamped file means you can reconstruct what happened when an agent goes off the rails, and you can grep across sessions to answer “did anyone touch the config schema today?”
Checkpoint before you context-switch
Before leaving a session idle, commit. Not a polished commit — a wip: checkpoint. The cost of a messy commit history on a feature branch is zero (squash it later). The cost of losing an hour of agent work to a bad edit is not.
The Cmd+Tab Problem — and How to Actually Navigate
macOS’s Cmd+Tab switches between applications, not windows. If all five agents live in one terminal app, Cmd+Tab gets you to the terminal and then abandons you. This is the single most common source of friction in parallel agent work, and it has concrete fixes:
| Shortcut | What it does | When to use it |
|---|---|---|
| Cmd+Tab | Cycle applications | Terminal → browser → editor |
| Cmd+` | Cycle windows within the current app | Hopping between agent windows — the key you’re missing |
| Cmd+1…9 | Jump to tab N directly | Fixed positional muscle memory for your top agents |
| Ctrl+←/→ | Switch Spaces | One Space per major workstream |
| Cmd+Shift+[ / ] | Previous / next tab | Linear sweep through all running sessions |
Three arrangement strategies
- Tabs with fixed positions. Agent 1 is always Cmd+1. Never reorder. Muscle memory does the rest.
- Split panes. iTerm2 or tmux panes let you see four agents at once. Peripheral vision catches a stalled prompt far faster than tab-cycling does.
- One Space per workstream. Backend agents on Space 2, frontend on Space 3. Ctrl+→ becomes a coarse context switch and your brain gets a spatial anchor.
Screen real estate is the hard constraint here — four readable agent panes needs roughly 32 inches or a vertical second display. A 34-inch USB-C ultrawide monitor on Amazon Japan → is the most direct upgrade for tiled agent work, and a dual-display USB-C dock on Amazon Japan → keeps a MacBook to a single cable. If you’re switching windows hundreds of times a day, a Mac-layout mechanical keyboard on Amazon Japan → with reachable modifier keys pays for itself in wrist comfort alone.
The Supervision Loop
Running agents in parallel converts your job from writing code to reviewing code and unblocking processes. A workable rhythm:
- Dispatch in a batch. Start all agents in one sitting with clearly scoped prompts. Staggered starts mean staggered interrupts all afternoon.
- Sweep every 10–15 minutes. Cycle every window, answer any blocked prompt, then leave. Do not read diffs during a sweep.
- Review in a dedicated block. When an agent reports done, review that diff properly — with full attention, in one place.
- Kill fast. An agent thrashing on the same error for three turns will not recover on the fourth. Stop it, tighten the prompt, restart.
The failure mode to watch for is shallow supervision: five branches that all look plausible and none of which you actually read. Parallelism multiplies output, and unreviewed output is a liability, not an asset. Susan Fowler’s Production-Ready Microservices on Amazon Japan → and the classic The Pragmatic Programmer on Amazon Japan → are both useful calibration for deciding what “done” means before you delegate it.
A Realistic Starting Configuration
Don’t start with eight agents. Start with three, on a machine with enough RAM to hold three toolchains and a browser without swapping — 32GB is the practical floor, and MacBook Pro models with 32GB on Amazon Japan → are where parallel agent work stops feeling sluggish.
- Window 1: the agent you’re actively conversing with. Highest attention.
- Window 2: a long-running task — test suite, migration, dependency upgrade. Check on a timer.
- Window 3: a read-only investigation agent. Zero risk, useful output.
Add a fourth only after this rhythm feels boring. The limit isn’t your CPU — it’s how many code reviews you can do in an afternoon.
Takeaways
- One worktree per agent. Isolation prevents the failure mode git can’t fix.
- Name your tabs and Spaces. Navigation cost compounds across hundreds of switches.
- Learn Cmd+`. It’s the window-level switch that Cmd+Tab doesn’t give you.
- Commit before switching. Checkpoints are free; lost work is not.
- Scale to your review capacity, not your hardware.
If manual window juggling becomes the bottleneck, Agent Desk (techathletes-store.web.app/agent-desk) lets you tile and manage multiple agents in a single view instead of hunting through terminal windows.
📝 More in-depth guides available on note.com: Follow @ksta877 on note.com for deep-dive OSS reviews, tutorials, and premium technical articles.
This post contains affiliate links. As an Amazon Associate I earn from qualifying purchases.