[FEATURE] Autonomous port allocation: Agents should not blindly compete for well-known ports across concurrent sessions

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When running multiple Claude Code sessions simultaneously across different projects, agents independently reach for the same well-known ports (3000, 8000, 8080) with no awareness of what other sessions are already using. This causes port conflicts that agents then try to resolve competitively - grabbing ports back from each other, killing processes, and in some cases entering infinite restart loops.
The deeper problem is that Claude Code can autonomously decide to spin up a server without any mechanism to coordinate port selection across sessions. The user never approved a specific port, the agent just picked one, and if two agents pick the same one the user is now debugging a problem they didn't create.
This affects anyone running concurrent agent sessions on the same machine - homelab users, developers working across multiple projects, or anyone doing rapid prototyping where multiple services come and go frequently.

Related closed issues confirming this is a real and recurring problem: #21496, #24990, #25464

Proposed Solution

A configurable port allocation range in settings.json that agents draw from autonomously, so port selection is deterministic and conflict-free without requiring user intervention:
json{
"portAllocation": {
"range": "8700-8999",
"mode": "autonomous"
}
}
autonomous — agent picks from the range without prompting
ask — agent requests confirmation before binding any port

Alternative Solutions

I built a named port registry called portbroker as a workaround.

Agents request a named reservation before starting any service. The same name always returns the same port across sessions, collisions are impossible, and it works across any CLI agent via a single AGENTS.md instruction. It solves the problem but requires a third party tool to work around something the agent itself is causing.
A reverse proxy is another common suggestion but it solves a different problem; service discovery and clean URLs, not port collision during autonomous server startup.

Priority

Critical - Blocking my work

Feature Category

Configuration and settings

Use Case Example

Use Case Example

I ask Claude Code in terminal one to build and run a web app. It spins up on port 3000.
I open a second Claude Code session in terminal two for a different project. It also tries port 3000.
Both agents detect the conflict and begin competing to claim the port, killing each other's processes.
I now have to intervene manually, find a free port, and explicitly tell both agents what to use - which defeats the purpose of autonomous agent workflows.

With a configured allocation range this never happens. Each agent draws a free port from the range, names it, and moves on.

Additional Context

I primarily use OpenAI Codex, where I have confirmed this problem firsthand, and have also seen it when using OpenCode. The port conflict behavior is well documented in this repo by other Claude Code users in the issues referenced above, so I am confident the same gap exists here.
The workaround I built (portbroker) was designed to be agent-agnostic precisely because this is not a Claude Code specific problem; it is a gap in how CLI coding agents in general handle autonomous server startup.

I am raising it here because Claude Code is the most active community and most likely to drive a native solution that benefits everyone.