Guide
How to run several coding agents on 1 Mac
In short
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.
Updated 9 October 2026. Checked with brainplane 0.2.2.
14 days free with every feature. Email only, no card.
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
- Give each agent its own working copy. A git worktree per task keeps edits apart:
git worktree add ../app-review -b review. - Keep the sessions running in 1 place. tmux, herdr, iTerm2 or Terminal all work. brainplane needs no special terminal.
- Share the decisions. Connect each agent to the same topic, so it reads the goal and the settled decisions instead of asking you.
- 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.
- Gather the questions. Each waiting agent sends its question to 1 Inbox, as 1 card per topic.
- 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.