# How to run several coding agents on 1 Mac

To run several Claude Code, Codex or Grok sessions on 1 Mac, give each its own working copy, keep 1 shared record of decisions, and gather their questions in 1 place. Terminal tools such as tmux and herdr keep the sessions running; brainplane adds the shared brain, file claims and 1 Inbox.

Canonical: https://brainplane.app/guides/run-multiple-coding-agents-on-mac/

## What breaks when you add a second agent

- **2 agents edit the same file.** One overwrites the other's change.
- **Context gets repeated.** You brief each session on the same goal and the same decisions.
- **Questions hide.** An agent waits for an answer in a terminal you are not looking at.
- **Limits run out.** Each run counts against your own plan, and nobody sees the total.

## A setup that holds up

1. **Give each agent its own working copy.** A git worktree per task keeps edits apart: `git worktree add ../app-review -b review`.
2. **Keep the sessions running in 1 place.** tmux, herdr, iTerm2 or Terminal all work. brainplane needs no special terminal.
3. **Share the decisions.** Connect each agent to the same topic, so it reads the goal and the settled decisions instead of asking you.
4. **Claim files.** A session can claim a task or a file for 30 minutes, and brainplane flags it when another live session writes the same file in that time.
5. **Gather the questions.** Each waiting agent sends its question to 1 Inbox, as 1 card per topic.
6. **Hand off, then review.** Let 1 agent write and another review, with checks that run before you read the result.

## Who does what

| Layer | Examples | Job |
|---|---|---|
| Isolation | git worktrees | Keep edits apart |
| Runtime | tmux, herdr, iTerm2, Terminal | Keep sessions alive and visible |
| Shared state and questions | brainplane | 1 brain per topic, file claims, handoffs with checks, 1 Inbox |

These layers combine. brainplane counts the agent sessions running in your terminals, in the background, in desktop apps and in herdr, and works alongside them.

## Name each session

brainplane gives each live session a short name: Alpha, Bravo, Charlie. The name shows on the tmux window and the herdr pane. Start a request with a name, typed or spoken, and it goes to that exact session after a 2 second hold.

## Keep an eye on usage

Every brainplane run is bounded: a handoff carries a time budget and a capped number of review rounds, and each context pack holds 3,000 tokens at most. When an agent reports a quota or login error, brainplane shows it on the card.

## Questions

### Does brainplane create worktrees for me?

No. Use git worktrees, or the tool you already use for isolation. brainplane tracks which session touched which file.

### Does brainplane lock files?

No. It does not lock files on disk. It records claims and flags a second writer. Agents you start yourself can still write anywhere their own settings allow.

### How many agents can I run?

As many as your Mac and your plans allow. brainplane works with Claude Code, Codex, Grok and 11 more agent tools.