DEV Community: Tj Thouhid

Port already in use? How to fix it when your AI coding agent keeps starting servers

Tj Thouhid — Wed, 21 Oct 2026 12:41:22 +0000

You ask your AI coding agent to run the app, and you get this:

Error: listen EADDRINUSE: address already in use :::3000

Or worse, you don't get an error at all. The agent's server quietly starts on 3001, your browser is still on 3000, and you spend ten minutes wondering why your change isn't showing up.

I wrote a general guide to finding and stopping whatever is using port 3000 on a Mac. This post is about the version of the problem that AI agents cause, because it happens a lot more often now, and it's easy to prevent once you know why.

Why AI agents leave servers running

Claude Code, Cursor, Codex and similar tools all run shell commands for you. That's useful, but dev servers are a bad fit for how they work:

Background servers. A dev server never finishes, so agents often start it in the background, check that the page loads, and move on. Nothing tells them to stop it later.
Re-runs. Later in the same session, or in a new session, the agent wants to test again. It doesn't know a server is already running, so it starts another one. Many dev servers (Vite, for example) quietly move to the next free port, so you end up with copies on 3000, 3001 and 3002.
Crashed or closed sessions. If the agent's session crashes, or you close the window, the server it started can keep running with no parent. On macOS it gets adopted by launchd and just sits there.
Several agents at once. Two agents on one project both want the same port. The second one either fails or picks a random port.

So the fix has two parts: clean up what's running now, then stop it happening again.

Step 1: find what's listening on the port

lsof -nP -iTCP:3000 -sTCP:LISTEN

-iTCP:3000 looks only at TCP on port 3000.
-sTCP:LISTEN shows only the process that's listening, which is the one holding the port. Without it you'd also see your browser's connections.
-n and -P skip name lookups, so it's faster and shows 3000 instead of a service name.

You'll get something like:

COMMAND   PID USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
node    48213 tj     23u  IPv6  0x...       0t0  TCP *:3000 (LISTEN)

To see every listening port at once, which is handy after a long agent session:

lsof -nP -iTCP -sTCP:LISTEN

Step 2: check what it is and who started it

Before you stop anything, find out what it is. Take the PID and ask ps:

ps -o pid,ppid,etime,command -p 48213

  PID  PPID  ELAPSED COMMAND
48213     1 01:12:40 node /Users/you/code/shop/node_modules/.bin/vite

command shows the full command line, which usually includes the project folder. That tells you which project it belongs to.
etime (shown as ELAPSED) is how long it's been running. An hour means it's not the server you just started.
ppid is the parent process. Run the same ps command on that PID to see what launched it. You'll often find a shell that belongs to your editor or AI tool. If the PPID is 1, the thing that started it has already gone, and this is a leftover.

If it's a database, Docker or something you didn't expect, stop and think before going further.

Step 3: stop it safely

Ask it to quit first:

kill 48213

This sends SIGTERM, a polite "please quit", so the server can close files and connections properly. Wait a couple of seconds and run the lsof command from step 1 again.

Only if it's still there:

kill -9 48213

kill -9 ends it straight away with no cleanup. Use it second, not first.

If you're sure the listener on 3000 is a leftover dev server and want one line, this stops only the process that's listening on that port:

kill $(lsof -t -iTCP:3000 -sTCP:LISTEN)

The -sTCP:LISTEN part matters. Without it, lsof also returns other processes connected to the port, such as your browser, and you'd send them the signal too.

If the server comes straight back after you stop it, something is restarting it, such as Docker, a process manager or a tool like Laravel Herd. Stop it there instead.

Step 4: stop it happening again

Cleaning up is fine once. Doing it every day gets old. These changes made the biggest difference for me.

Give each agent a fixed port. Put it in the project's .env:

PORT=3001

And make the dev server fail instead of drifting to a random port. For Vite:

npm run dev -- --port 3001 --strictPort

A server that fails loudly on a busy port is much easier to deal with than one that silently moves to 3004.

If you run more than one agent on the same project, give each one its own folder (a git worktree) and its own port, so they never compete for 3000.

Write the rules down for the agent. Agents read CLAUDE.md (Claude Code) or AGENTS.md (Codex and others). Add a short section:

## Dev server
- Run it with: `npm run dev -- --port 3001 --strictPort`
- Use port 3001 only.
- Before starting a server, check if one is already running:
  `lsof -nP -iTCP:3001 -sTCP:LISTEN`. If it is, reuse it.
- Stop any server you started when the task is done.

This one change cut my duplicate servers by more than anything else.

Stop servers when you're done. At the end of a session, ask the agent to stop what it started, or run lsof -nP -iTCP -sTCP:LISTEN yourself and clear out anything left over. It takes ten seconds and saves the confusing "why is my old code showing?" moment the next morning.

Doing this in Lokstack

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

I got tired of running these commands after every agent session, so Lokstack does the looking for you. Search for a port and it shows what's using it, which project it belongs to and who started it. Stop asks the program to quit, like kill. Force stops it straight away, like kill -9. The Agents screen has a Left running panel that lists the dev servers AI tools started and didn't stop. All of that is on the free plan.

Here's a short video of finding and freeing a busy port:

If you'd rather stay in Terminal, the commands above are all you need. https://lokstack.app

What's the most servers you've found an agent left running? Tell me in the comments.

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

Tj Thouhid — Wed, 21 Oct 2026 12:40:16 +0000

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:

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.
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.
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.
The same .env file. If one agent changes a setting to test something, every other agent gets that change too.
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

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

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

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

npm run dev -- --port 3002 --strictPort

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

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

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"

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

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

PORT=3001
DATABASE_URL=postgres://localhost:5432/shop_claude

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.

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

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

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

lsof -nP -iTCP -sTCP:LISTEN

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>

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.

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.

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.

What's using port 3000 on my Mac? Find it, see who started it, and stop it safely

Tj Thouhid — Sun, 18 Oct 2026 13:07:56 +0000

You run npm run dev and get this:

Error: listen EADDRINUSE: address already in use :::3000

The usual advice is "find the PID and kill it". That works, but it skips the questions that actually matter. What is on port 3000? Which project does it belong to? Did I start it, did my editor, or did an AI agent start it in the background an hour ago? And is it safe to stop?

Here's how to answer all of that on macOS with commands that are already installed. After that, I'll show how I do the same thing in a Mac app I build.

1. A quick look

lsof -i :3000

On macOS, plain lsof -i :3000 may print a service name such as hbci instead of 3000; step 2 fixes that.

This lists every process with a network connection on port 3000. That includes the server, but also your browser tabs that are connected to it, so the list can be longer than you expect.

2. Just the thing that's listening

lsof -nP -iTCP:3000 -sTCP:LISTEN

-iTCP:3000 limits it to TCP on port 3000.
-sTCP:LISTEN shows only the process that's listening, which is the one holding the port.
-n and -P skip name lookups. It's faster, and you see 3000 rather than a service name.

You'll get something like:

COMMAND   PID USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
node    48213 tj     23u  IPv6  0x...       0t0  TCP *:3000 (LISTEN)

You might see two lines, one for IPv4 and one for IPv6. They can even be two different processes. That's how you get the confusing case where the browser shows an old version of your app while your terminal says the new one started fine.

3. What is it, who owns it, and for how long?

Take the PID and ask ps:

ps -p 48213 -o pid,ppid,user,etime,command

  PID  PPID USER  ELAPSED COMMAND
48213 48190 tj   01:12:40 node /Users/tj/code/shop/node_modules/.bin/vite

command is the full command line. It often includes the project path (/Users/tj/code/shop here), which is usually the quickest way to tell which project it belongs to.
etime (shown as ELAPSED) is how long it's been running. An hour and twelve minutes means this isn't the server you just tried to start.
user is who owns it. If it isn't you, see step 4.
ppid is the parent process. Run the same command on it to see what launched it:

ps -p 48190 -o pid,ppid,user,etime,command

Keep going up and you'll usually hit zsh and then Terminal, an editor's helper process (VS Code, for example), or an AI tool's shell. If the PPID is 1, the original parent has exited and macOS's launchd adopted the process. That's typical for a server left running in the background after the thing that started it went away.

4. Nothing shows up? It may belong to another user

lsof only lists your own processes unless you run it with sudo:

sudo lsof -nP -iTCP:3000 -sTCP:LISTEN

If the port is held by a process owned by root or another user, this is how you'll see it.

5. Stop it, gently first

kill 48213

kill sends a polite "please quit" signal (SIGTERM), so the program can shut down properly. Give it a couple of seconds and run the lsof command from step 2 again. Only if it's still there:

kill -9 48213

kill -9 ends it immediately, with no chance to clean up. Use it as the second step, not the first.

A few things to watch for:

Another user's process. You'll get "Operation not permitted". You'd need sudo kill 48213, so first be sure it's really something you mean to stop.
Still busy after you stopped it? Dev servers often start child processes. Run step 2 again and see what's listening now.
It comes straight back? Something is restarting it, such as a service manager, Docker, or an app like Laravel Herd. Stop it there instead of killing it again.
Ports 5000 and 7000. On recent macOS versions, AirPlay Receiver listens on these. If a Flask app can't get port 5000, that's probably why. Pick another port, or turn AirPlay Receiver off in System Settings.

The same thing in Lokstack

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

I built Lokstack partly because I got tired of running these commands one after another. It's a free Mac app, and everything in this section is on the free plan.

Ports page. Search for 3000. Lokstack shows which program holds the port, which project it belongs to, who started it, and how long it's been up. There are two buttons. Stop asks the program to quit, like kill. Force stops it straight away, like kill -9.

"Why won't it start?" on a project's Overview. If the project has a saved port and something else is using it, a red box says "Port 3000 is already taken" with a Free port 3000 button. That's the one-click version.

Run & logs. If the app you start prints EADDRINUSE or "address already in use", Lokstack explains it in plain words and offers the same fix.

What it won't do, so you know where the edges are:

Databases and services are protected. Lokstack won't stop them by accident.
Programs owned by another user (for example a server running as root) can't be stopped from Lokstack. It says "Permission denied", and in Terminal you'd need sudo.
Laravel Herd sites are stopped by asking Herd to stop all its services, not by killing that one process.
The Free port button only appears for projects with a saved port. Stop and Force on the Ports page always work.

Wrapping up

When you see EADDRINUSE, find out what's actually listening, check what it is and who owns it, and stop it gently before you force it. If it keeps coming back, stop it where it's managed (Docker, a service manager, Herd) instead.

Lokstack is a free Mac app that shows what is using a port, which project it belongs to and who started it, and lets you stop it in one click. It won't touch your databases by accident. If you'd rather stay in Terminal, the commands above are all you need. https://lokstack.app

What's the strangest thing you've found holding a port? I'd like to hear it in the comments.