Your Dev Setup Is Why AI Agents Aren't Working For You

Git worktrees sound cool until you actually try them.

You see the demo, you get the idea. Multiple branches, no stashing, agents working in parallel. So you set it up. Then you spend 45 minutes debugging why nothing boots, ports are colliding, and the database is throwing fits. You didn’t even write any code yet.

Most people close the tab. Understandable.

Worktrees work though. They were fine. Your setup was cooked.

The First Problem Is Always Stupid

I ran into this working on an internal project. Multiple features, multiple agents, the whole thing. Spun up worktrees, pointed agents at them, ready to go.

First problem? Port conflicts. Not something complicated. Just two environments trying to use the same port. Simple. Stupid. Made me wanna scrap the whole setup and go back to one agent.

That’s how bad setup kills good ideas. It doesn’t have to be a big problem. It just has to be annoying enough that you do the math and decide it’s not worth it.

One Line

The fix was one line:

port := `printf '%s' "$(basename "$PWD")" | cksum | awk '{print 3000 + ($1 % 57000)}'`

Deterministic port from the worktree directory name. Same worktree, same port every time. No config, no collisions.

Pair that with a justfile that boots everything in one command:

dev:
    pnpm web -- --port {{port}}

New worktree, run just dev, you’re running. That’s it.

Dialed in setup means a new environment is running in under 60 seconds with zero decisions. If you’re manually wiring anything when you spin up a worktree, you’re not ready for parallel agents yet.

What It Actually Looks Like

Once this was solid, the workflow actually worked.

Five agents running at once, each in its own worktree, own port, own environment. All working on small changes I knew needed to get done but didn’t wanna stop and context switch for. Not hard stuff, just annoying stuff. The kind of tasks that sit on the backlog forever because they’re not worth a branch and a full review cycle.

Worktrees killed that excuse. Spin one up, drop an agent in, let it run. You stay focused on the thing that actually needs your attention.

The small stuff just gets done now.

The Checklist

Three things your setup needs before parallel agents actually work:

One-command boot. New worktree, one command, full environment running. No manual steps.

Full isolation. Deterministic ports, separate databases, Docker where it matters. Agents don’t share, agents don’t collide.

Reproducibility. Whatever works in your main environment works in every worktree.

Do the Audit

Audit your setup. Could a fresh worktree be running in under 60 seconds?

If not, that’s the problem. Fix the setup first.

— Iverson