DEV Community

Tj Thouhid
Tj Thouhid

Posted on

How to run multiple AI coding agents on one Mac without port clashes

#ai #git #macos #webdev

Running one AI coding agent on a project is easy. Running two or three at once on the same Mac is where it gets messy. I've had Claude Code fixing a bug while Codex worked on a feature in the same repo, and an hour later I found two dev servers on two ports, a branch with both agents' changes mixed together, and test data in my local database that neither of them should have touched.

None of this is the agents' fault. They're all working in one shared place. The fix is to give each agent its own space. Here's how I set that up by hand, with plain commands, and what to clean up afterwards.

Why agents collide

When two agents work on one project, they usually share five things:

  1. The same branch and working tree. Both agents edit the same files on disk. One agent's half-finished change breaks the other agent's test run, and the commit history ends up a mix of both.
  2. The same dev server port. Each agent runs npm run dev to check its work. The first one gets port 3000. The second one either fails with EADDRINUSE or quietly moves to 3001, and then you're not sure which browser tab is showing whose code.
  3. The same database. One agent runs a migration or seeds data, and the other agent's tests start failing for reasons that have nothing to do with its own change.
  4. The same .env file. If one agent changes a setting to test something, every other agent gets that change too.
  5. Leftover servers. Agents often start a server in the background and never stop it. After a few sessions you have old copies of your app running on ports you didn't pick.

So the goal is simple: one branch, one folder, one port, one database and one .env per agent.

Step 1: one git worktree per agent

A git worktree is a second (or third) folder that's linked to the same repository but checked out on its own branch. Each agent gets its own folder, so they never edit the same files on disk.

From your main project folder:

git worktree add ../shop-claude -b agent/claude-fix-cart
git worktree add ../shop-codex  -b agent/codex-search
Enter fullscreen mode Exit fullscreen mode

Now you have:

  • shop/ on your main branch (yours)
  • shop-claude/ on agent/claude-fix-cart
  • shop-codex/ on agent/codex-search

Open each agent in its own folder. To see what you have at any time:

git worktree list
Enter fullscreen mode Exit fullscreen mode

Two things catch people out:

  • Ignored files are not copied. A new worktree has no node_modules, no .env and no local database file. Run npm install (or your package manager) in each one.
  • One branch can only be checked out in one worktree. That's a good thing. It stops two agents from working on the same branch by accident.

Step 2: a fixed port per agent

Give each worktree its own port and tell the agent about it. Most frameworks read a PORT value or take a flag.

For Next.js and many Node servers, PORT is enough:

# in shop-claude/
PORT=3001 npm run dev
Enter fullscreen mode Exit fullscreen mode

For Vite, pass the port and make it fail instead of quietly picking another one:

npm run dev -- --port 3002 --strictPort
Enter fullscreen mode Exit fullscreen mode

--strictPort matters. Without it, Vite moves to the next free port, which is exactly how you end up with mystery servers on 3003 and 3004.

I keep a tiny table in my notes: main is 3000, Claude is 3001, Codex is 3002. Boring, but it means I always know which tab is which.

Step 3: a database copy per agent

If your agents run migrations or write test data, give each one its own copy.

Postgres. createdb can copy an existing database as a template:

createdb -T shop_dev shop_claude
createdb -T shop_dev shop_codex
Enter fullscreen mode Exit fullscreen mode

This only works when nothing is connected to shop_dev, so stop your dev server first. If it complains that the source database is in use, that's why.

MySQL. There's no template option, so dump and load:

mysql -e "CREATE DATABASE shop_claude"
mysqldump shop_dev | mysql shop_claude
Enter fullscreen mode Exit fullscreen mode

SQLite. It's just a file. Copy it while nothing is writing to it, or use SQLite's own backup command, which is safe even if the file is open:

sqlite3 ../shop/dev.db ".backup dev.db"
Enter fullscreen mode Exit fullscreen mode

Then point each worktree at its own database in its .env.

Step 4: a separate .env per worktree

Since worktrees don't get your ignored files, copy the .env in and change the parts that must differ:

cp ../shop/.env .env
Enter fullscreen mode Exit fullscreen mode

Then edit it, for example in shop-claude/.env:

PORT=3001
DATABASE_URL=postgres://localhost:5432/shop_claude
Enter fullscreen mode Exit fullscreen mode

Keep real secrets out of anything the agent might commit. Check that .env is in .gitignore in every worktree before you let an agent loose on it.

Step 5: tell each agent the rules

Agents follow written instructions well. In each worktree, add a short note to CLAUDE.md or AGENTS.md:

## Local dev
- Dev server: `PORT=3001 npm run dev` (use port 3001 only)
- If a server is already running on 3001, reuse it. Don't start another.
- Database: shop_claude (never shop_dev)
- Stop any server you started when the task is done.
Enter fullscreen mode Exit fullscreen mode

This cuts down on duplicate servers more than anything else I've tried.

Step 6: clean up when an agent is done

When the work is finished, you have three choices: merge it, keep it for later, or throw it away.

Merge it:

cd ../shop
git merge agent/claude-fix-cart
Enter fullscreen mode Exit fullscreen mode

Throw it away (or clean up after merging):

git worktree remove ../shop-claude
git branch -D agent/claude-fix-cart   # -D deletes even if unmerged
dropdb shop_claude
Enter fullscreen mode Exit fullscreen mode

Check for leftover servers. This lists everything listening on a TCP port:

lsof -nP -iTCP -sTCP:LISTEN
Enter fullscreen mode Exit fullscreen mode

Look for node, python, php or ruby processes on ports you weren't expecting. To see which folder one came from:

ps -o pid,ppid,etime,command -p <pid>
Enter fullscreen mode Exit fullscreen mode

The command line usually includes the project path, so you can tell whether it's from shop-claude or shop-codex. Stop it gently with kill <pid>, and only use kill -9 <pid> if it's still there a few seconds later.

The same setup in Lokstack

Disclosure: I build Lokstack, a Mac app, and this part is about my own app.

The steps above work, but it's a lot of setup and cleanup for every task. Lokstack has a feature called lanes that does this per agent. Each AI agent (Claude Code, Cursor, Codex) gets its own lane: its own branch, its own port and its own database copy. When the agent is finished, a finish screen asks what should happen to the work: Add it to main, Open a pull request, Keep it for later or Throw it away. Your main branch and main database aren't touched until you choose.

Lokstack lane finish screen: add it to main, keep it, or throw it away

The Agents screen also has a Left running panel that lists the dev servers agents started and didn't stop, so you can stop them from there.

Lokstack Agents screen with three lanes and the Left running panel

A 43-second demo of lanes:

To be upfront: lanes are a Pro feature and they're in beta. They work and have passed a full test pass, but details may change between releases. There's a 14-day free trial with no card. For launch, Pro is 50% off the first year ($39.99 instead of $79.99) with code LAUNCH50.

If you'd rather do it by hand, everything in this post is plain git and shell, and it works fine. https://lokstack.app

How many agents do you run on one project at once, and what breaks first for you? I'd like to hear it in the comments.

Top comments (0)