Skip to content
Edith

Guide

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.

Updated by

Get Edith

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 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.

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.

  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.

  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.

  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.

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 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 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.

Clean up afterwards

Worktrees pile up. Edith's disk cleaner for developers 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.

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.