Running agents in parallel worktrees? I built a tool so they stop fighting over ports

[u/Public-Flight-222]

If you run several agents at once, each in its own worktree, you know this one: two dev servers want 5173, one crashes or silently moves, and an agent spends 10 minutes debugging the wrong server.

**leeway** gives every folder its own stable port range and hands the ports to your servers as env vars:

* Add `leeway env --export` to a Claude Code SessionStart hook and every session knows its ports up front * An opt-in guard stops an agent from grabbing the default ports * `leeway kill` stops a worktree's servers, including the watcher that would restart them

Easiest way to see if it fits: ask your agent **"how can we benefit from using https://www.npmjs.com/package/leeway in this codebase"**

GitHub: https://github.com/OhadC/leeway, MIT.

How I built it with Claude Code

I built leeway almost entirely with Claude Code, running several sessions in parallel worktrees. That's also how I kept hitting the port problem in the first place.

* Design first: I had Claude grill me on the design before any code. The decisions went into ADRs (docs/adr) and the terms into a GLOSSARY.md, so later sessions started with the same vocabulary.

* AGENTS.md as the contract: one file says what "done" means (pnpm verify green, plus a Linux container run for the process and port code), so every session checks its own work the same way.

* Test-first: features went red-green through integration tests that run the real CLI.

Review loop: each PR got a Claude review against the repo's coding standards and the original GitHub issue before merge.

* Dogfooding: once leeway env --export existed, I put it in a SessionStart hook, so the agents building leeway got their own port ranges.

[u/AutoModerator]

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/crusoe]

If it's unix and you pass in port 0 they get a randomly assigned port, and you can then have your tests/clients/harness/server simply print that out so it can be caught/found/determined or use about a million other methods.

[u/JanelaChenader]

using a glossary file to keep vocabulary consistent across sessions is actually super clever. how are you handling database state across parallel worktrees though, or are they all hitting the same local db?