How to Run Multiple Coding Agents on One Machine (Without Collisions)

One coding agent is a tool. Four of them on the same laptop is an operations problem — and it fails in four specific, boring, entirely preventable ways. This is the procedure we run on a 10-core Mac that hosts Claude Code, Codex, and background agent sessions at the same time: how to isolate working trees, own ports on purpose, sweep the processes nobody kills, and stop every session from arguing about what is running.

The pitch for parallel agents is obvious. One session refactors the API while another writes the tests while a third fixes a build. In practice, the second agent you start is where the trouble begins, and almost none of it is about model quality. It is about two processes sharing one filesystem, one port range, and one process table.

The four collisions, in the order you will hit them

1. Two sessions, one working tree

This is the first one and the worst one. Two agents in the same checkout are two writers with no lock. Agent A reads src/auth.ts, thinks for ninety seconds, and writes its version back — over the edit agent B made in the meantime. Nothing errors. Both agents report success. You find out at review time, or you do not find out at all.

It gets louder when git is involved: one agent stages files it did not write, or runs git checkout .to “clean up” and discards forty minutes of the other agent's work. Neither agent is misbehaving. They are each doing the correct thing in a world where they are alone, and they are not alone.

2. Port ownership nobody assigned

Agent A starts a dev server. It binds 3000. Agent B starts the same project's dev server, finds 3000 busy, and — depending on the framework — either fails, or silently moves to 3001, or attaches to the running one. Now agent B is testing agent A's build. It curls a URL, sees the old behavior, and concludes its change did not work. So it “fixes” code that was already correct.

The most expensive agent failures are not wrong code. They are correct code, reverted, because the agent verified against something it did not own.

3. Processes that outlive the session that started them

Every MCP server your agent uses is a child process. Kill the terminal, crash the session, close the tab — and some of those children get reparented to PID 1 and keep running, holding ports and RAM. One session leaves two or three. A month of daily work leaves a crowd.

Concrete, from the machine this was written on, mid-session:

$ ps -eo pid,ppid,etime,command | grep -i mcp | grep -v grep | wc -l
      50

# reparented to PID 1 = the session that started it is gone
$ ps -eo pid,ppid,etime,command | awk '$2==1' | grep -i mcp | grep -v grep
   4711     1 21-14:33:07 node /.../some-mcp-server/dist/index.js

Fifty MCP processes for a handful of live sessions is normal for a fleet box. One of them had been running, orphaned, for twenty-one days. It was doing nothing except holding memory and confusing every future health check.

4. Stale state, believed confidently

The subtlest one. An agent reads a project doc that says “the API runs on :8000”, or recalls from earlier in the conversation that a service is up, and proceeds on that basis. Model memory is a cache with no invalidation. Multiply by four sessions and you get four agents holding four different, equally confident beliefs about one machine — and the machine agrees with none of them.

Fix 1: one git worktree per agent

The instinct is to clone the repo four times. Do not — you will fight four sets of remotes and four copies of node_modules that drift. Git has the right primitive built in. git worktree gives each agent its own directory and its own checked-out branch, sharing one .git object store.

# from your main checkout
$ git worktree add ../myapp-agent-b -b feat/agent-b
$ git worktree add ../myapp-agent-c -b fix/agent-c

$ git worktree list
/Users/you/code/myapp            9f2c1ab [main]
/Users/you/code/myapp-agent-b    9f2c1ab [feat/agent-b]
/Users/you/code/myapp-agent-c    9f2c1ab [fix/agent-c]

# when the work merges
$ git worktree remove ../myapp-agent-b
$ git worktree prune

Now start each agent session with its working directory set to its own worktree. Overwrites become structurally impossible rather than merely discouraged, and each agent's branch is a real branch you can review and merge normally.

The three things people get wrong with worktrees on an agent box:

• Untracked files do not come with you. A new worktree has no .env, no node_modules, no build cache. Copy the env file and install dependencies as part of creating the worktree, or the agent's first act will be to debug a missing config it cannot see.
• You cannot check out the same branch twice. Git refuses, which is a feature. Give each worktree its own branch even if the work is small.
• Nested worktrees inside the main checkout confuse tooling. Put them as siblings (../myapp-agent-b), not children, or watch your linter walk into them.

Fix 2: assign ports, never discover them

Auto-port-selection is a convenience feature that becomes a correctness bug the moment there are two of you. Pin a port per lane and pass it explicitly, so an agent that binds nothing fails loudly rather than silently attaching to someone else's server.

# lane B owns 3001, lane C owns 3002 — decided by you, not by the framework
$ PORT=3001 npm run dev

# who actually holds what, right now
$ lsof -nP -iTCP -sTCP:LISTEN
COMMAND   PID  USER  FD  TYPE  NODE NAME
node     8123   you  24u IPv6  TCP  *:3001 (LISTEN)
node     8455   you  22u IPv6  TCP  *:3002 (LISTEN)

# is the thing I am about to curl mine?
$ lsof -nP -iTCP:3001 -sTCP:LISTEN -t
8123

The rule that makes this pay: an agent may only verify against a port it started in this session.If it did not start the server, it does not get to conclude anything from the response. That single rule kills the whole class of “my change did not take effect” false negatives.

Fix 3: sweep the orphans on a cadence you actually keep

Leaked processes do not announce themselves. They show up as a laptop that got slow, a port that is mysteriously taken, and a fan that runs at a desk where nothing is happening. Two commands find them.

# 1. everything agent-shaped that was reparented to init
$ ps -eo pid,ppid,etime,command | awk '$2==1' | grep -Ei 'mcp|claude|codex' | grep -v grep

# 2. sanity-check the box itself
$ sysctl -n hw.ncpu     # macOS   (Linux: nproc)
10
$ uptime
14:29  up 12 days,  4:16, 2 users, load averages: 3.73 3.52 2.56

# 3. kill by PID, one at a time, after you have read the command line
$ kill 4711

And one hard rule we learned the expensive way: if you ever wire cleanup to a scheduler, check for a self-healer first. We once spent an afternoon killing background jobs that a cron entry was re-bootstrapping every two minutes. Disk hit the floor and load average went to three digits before anyone looked at crontab -l. Kill the respawner before you kill the process.

Fix 4: ground every session in what the OS says, not what the docs say

The fourth collision is fixed by making observation the cheapest possible action. If checking is one tool call, agents check. If checking means the human runs three commands and pastes the output, agents guess.

That is exactly the gap we wrote whats-running-mcp to close — a free, MIT MCP server that reads live agent sessions, listening ports, loaded daemons, and system load straight from ps, lsof, launchctl and df, and hands them to the model as structured tool output. It exists because our own sessions kept reporting dead services as healthy.

$ claude mcp add --scope user whats-running -- npx -y whats-running-mcp

It is free and stays free. The install command, the other two servers in the set, and the two paid kits live on our agent tools page.

How many agents can one machine actually take?

There is no universal number, but there is a usable heuristic, and it is not “one per core.” Agent sessions are mostly idle — they wait on the network for tokens. What saturates the box is what they start: dev servers, test runners, browsers, build watchers, and a dozen MCP children each.

• Watch load average against core count, not CPU percentage. On the 10-core box above, a load average of 3.73 with several live sessions is comfortable. Sustained load near or above your core count means work is queuing, and every agent gets slower together.
• RAM is the real ceiling. Each headless browser is hundreds of megabytes. Two agents each running a browser and a test suite will hit swap long before they hit CPU.
• Disk is the silent one. Four worktrees times node_modules plus build caches plus a month of logs fills a drive quietly, and a full disk produces failures that look like everything except a full disk.

Practical answer from running this daily: three or four concurrent sessions on a 10-core / 32 GB machine is fine if only one or two of them are running heavy processes at a time. The limit you hit first is almost never the model — it is your own attention across four review queues.

The operating procedure, start to finish

1. 1Before starting a second agent: create its worktree, copy the env file, install dependencies, assign its port. Isolation is set up once, not negotiated later.
2. 2At session start:the agent asks the OS what is running — live sessions, held ports, loaded daemons — and works from that, not from a doc listing services that “should be” up.
3. 3During work:an agent verifies only against processes it started. Anything else is another lane's output and proves nothing about its own change.
4. 4At session end: close what you opened. Stop the dev server, kill the debug browser, remove the merged worktree. The discipline of closing is what keeps the sweep in step 5 short.
5. 5Weekly: list orphans reparented to PID 1, read the command lines, kill by PID. Check free disk. Ten minutes, and the box stays fast for months instead of degrading until you reboot in frustration.

Honest limits

Worktrees isolate files, not databases. If four agents share one local Postgres, they share one schema, and a migration in lane B breaks lane C. Either give each lane its own database (separate container, separate port — same discipline as above) or accept that database work is a single-agent lane.

Isolation also does not create review capacity. Four agents produce four branches, and every branch still needs a human decision. Parallelism moves your bottleneck from typing to reviewing; it does not remove it. And a fleet does not fix an agent that reports success without checking — that is a separate failure with a separate fix, covered in your agent says it's done and it isn't.

The bottom line

Running four coding agents on one machine is not a scaling problem, it is a hygiene problem. Give every agent its own worktree so it cannot overwrite a peer. Assign ports so it cannot verify against a stranger's server. Sweep orphans so the box does not silently fill with processes nobody owns. And make “what is actually running?” a one-call question so no session has to guess.

Start with the free server — whats-running-mcp, MIT, no telemetry, one install command. If you want the whole procedure rather than the parts, the Agent Fleet Ops Kit ($29) is this article as working tooling. Related reading: why your context window is half spent before you type and the MCP servers we actually run.