# How to Run Multiple Claude Code Agents on Mac

> Isolate each agent in its own worktree, then keep track of all of them without juggling terminal tabs.

- Canonical URL: https://getedith.pro/guides/run-multiple-claude-code-agents-mac
- Published: 2026-11-15
- Updated: 2026-11-15

## The short answer

Give every agent its own git worktree so their edits never collide, then start one Claude Code session per worktree. Claude Code does the first part for you with `claude --worktree <name>`. The hard part is keeping track: which agent is waiting for an answer, which one finished, and which one is quietly burning your limit. That is what a board like Edith's [run multiple Claude Code agents](https://getedith.pro/extensions/coding-agents) extension, Agents, is for.

## Step 1: one worktree per agent

Built into Claude Code

### Start Claude in its own worktree

Pass `--worktree`, or `-w`, with a name. Claude Code creates the worktree under `.claude/worktrees/<name>` at the repository root, on a new branch called `worktree-<name>`, and starts the session inside it. Run the same command with a different name in a second terminal for a second agent.

```
 claude --worktree feature-auth
 claude --worktree fix-flaky-tests
```

When you exit, Claude removes a clean worktree and its branch, or asks first if you named the session, and asks whether to keep a worktree that has changes or new commits. A `.worktreeinclude` file at the project root copies ignored files such as `.env` into each new worktree. Add `.claude/worktrees/` to your `.gitignore`. The details are in Anthropic's [worktrees documentation](https://code.claude.com/docs/en/worktrees).

You can also manage worktrees with git directly, which is useful when you want one on an existing branch or outside the repository:

```
 git worktree add ../project-feature-a -b feature-a
 cd ../project-feature-a && claude
 git worktree list
 git worktree remove ../project-feature-a
```

## Step 2: watch them with agent view

Built into Claude Code

### Open claude agents

`claude agents` opens agent view, a research preview that lists your background sessions grouped by state: needs input, working, ready for review and completed. Run `/bg` in a session to send it there. You can peek at a session, attach to it, or type a new task at the bottom to start another.

## Where the built-in tools fall short

- **Claude Code only.** Agent view shows Claude Code sessions. A Codex or Gemini agent working on the same repository is invisible to it.
- **One Mac.** If you also run agents on a desktop at home or a Linux box over SSH, each machine is its own island.
- **Tabs, not layouts.** Watching four agents means four terminal tabs or a tmux layout you maintain by hand.
- **No scheduled messages.** A message you type while Claude is working waits for the current turn, but only in the session you are typing in. You cannot schedule one for a set time, or send it from a script or another machine.

## The Edith way: Agents

Agents is a board of every coding agent running on your Mac and on the machines you added in Edith's Machines extension. It groups them as blocked, working, done or idle, puts blocked agents first, and lets you open any of them to read its terminal and reply. It runs agents in Herdr, a terminal workspace that keeps each agent alive in its own pane so you can leave and come back. Edith offers a one-click Herdr install the first time.

1. 1
   ### Install Agents and Herdr
   Install the extension, open it, and press Install Herdr if it asks. Machines you add over SSH need their own copy of Herdr.
   `ed extensions install herdr`
2. 2
   ### Start agents side by side
   Press New Agent and choose the agent, the machine and the space. Claude Code, Codex, OpenCode, Cursor Agent, Pi, Gemini and Amp are all options. Each one opens in its own pane.
3. 3
   ### Arrange the panes
   Apply a built-in layout such as columns, rows or grid to a tab, or save your own split and reuse it.
   `ed herdr layout apply grid`
4. 4
   ### Answer the blocked ones
   Edith tells you when an agent is blocked on a question or a permission prompt. Open it from the board to answer. `ed herdr ls` lists every pane with its id and state.
   `ed herdr ls`
5. 5
   ### Queue the next instruction
   Name a pane from `ed herdr ls`, and `--when-finished` types the message into that agent the next time it finishes a turn. `--in 1h` or `--at 16:30` sends it at a set time instead, and `working` or `stopped` in place of a pane sends to every agent in that state right away.
   `ed herdr send w1:p2 "run the tests and fix failures" --when-finished`

Other commands worth knowing:

```
 ed herdr models
 ed herdr defaults ls
 ed herdr attach w1:p2
 ed herdr hooks ls
 ed herdr gather
```

`models` lists the models, effort levels and fast mode each agent offers, and `defaults` sets what Edith passes when it starts one. `attach` connects your current terminal to a live pane. `hooks ls` shows queued messages, and `gather` pulls every tab into one view.

## Review what the agents wrote

Parallel agents produce parallel branches. Edith's [pull request review workspace](https://getedith.pro/extensions/code-review) opens each worktree of a project as its own review session, so you can read the changes from three agents in three tabs without checking anything out by hand. From a terminal, `worktrees` lists every checkout of a project and `sessions` lists the review tabs open in Edith.

```
 ed quinjet projects
 ed quinjet worktrees ~/code/my-app
 ed quinjet sessions
```

For plain shells next to your agents, Edith's [terminal with broadcast input](https://getedith.pro/extensions/terminal) opens tabs with `⌘T` and can type one command into every tab at once, which is handy for pulling the same branch in several worktrees.

Watch your limits

Four Claude Code agents use a 5-hour window about four times as fast as one. Keep [Usage](https://getedith.pro/extensions/claude-code-usage) in the menu bar and turn on its alerts, and read [how to check Claude Code usage limits](https://getedith.pro/guides/check-claude-code-usage-limits) before a big parallel run.

## Clean up afterwards

Worktrees pile up. Edith's [disk cleaner for developers](https://getedith.pro/extensions/disk-cleaner) finds linked worktrees you have not touched in a while and moves them to the Trash. It skips worktrees with uncommitted changes, and the branch and its commits stay in the repository.

```
 ed cleaner worktrees --root ~/code --older-than 1w
 ed cleaner clean --root ~/code --category worktrees --older-than 2w --yes
```

To leave agents running after you close the laptop, see [run coding agents overnight](https://getedith.pro/use-cases/run-coding-agents-overnight).

## Common questions

### How many agents can I run at once?

There is no fixed number in Edith. The practical limits are your plan's rate limits, memory for each agent's tools and builds, and how many reviews you can keep up with.

### Do I need agent view if I use Edith?

No, but they work fine together. Agent view is good for Claude Code background sessions on one Mac. The Agents board adds other agents and other machines.

## Edith extensions used

- [Run Multiple Claude Code and Codex Agents on Mac](https://getedith.pro/extensions/coding-agents): See every coding agent on your Macs in one board, and step in when one needs you.
- [Review Pull Requests on Mac in a Terminal Workspace](https://getedith.pro/extensions/code-review): Review GitHub pull requests and code changes in a focused terminal workspace.
- [Terminal With Broadcast Input and Tabs for Mac](https://getedith.pro/extensions/terminal): A fast built-in terminal with tabs that keeps your shells in one place.
- [Claude Code Usage Tracker for Mac: Codex, Cursor](https://getedith.pro/extensions/claude-code-usage): See what your coding agents cost and how close you are to their limits.
- [Clear Xcode Cache and Developer Junk on Mac](https://getedith.pro/extensions/disk-cleaner): Get back disk space from caches and leftovers, safely.

## Related guides

- [How to Check Claude Code Usage Limits on Mac](https://getedith.pro/guides/check-claude-code-usage-limits): Check Claude Code usage limits on your Mac with /usage, claude.ai settings and the status line, or keep the 5-hour and weekly limits in the menu bar.
- [How to Add an MCP Server to Claude Code on Mac](https://getedith.pro/guides/add-mcp-server-claude-code): Add an MCP server to Claude Code on a Mac with claude mcp add, pick the right scope, check it with /mcp, and connect Edith's tools in one command.
