[FEATURE] preview_start should detect actual server port from stdout instead of requiring static port config
Summary
When a dev server's configured port is already in use, many frameworks (Vite, Next.js, webpack-dev-server, etc.) automatically increment to the next available port and print the actual URL to stdout. The preview tool should parse this output to connect to the correct port, rather than relying solely on the port or autoPort fields in launch.json.
Current behavior
launch.jsonhas noportfield;pnpm startrunsvite --host localhost --port 3000 --open- Port 3000 is occupied (e.g., by a main dev server), so Vite auto-increments to 3003 and prints:
```
Port 3000 is in use, trying another one...
Port 3001 is in use, trying another one...
Port 3002 is in use, trying another one...
VITE v5.4.21 ready in 140 ms
➜ Local: http://localhost:3003/
```
- The preview tool's headless browser does not connect to 3003 — it stays on "Awaiting server..."
Setting autoPort: true makes it worse: the tool assigns a random port (e.g., 63364) via the PORT env var, but Vite ignores PORT because --port 3000 is hardcoded in the npm script. The server ends up on 3003 while the preview points at 63364.
Expected behavior
The preview tool should parse the server's stdout for common URL patterns (e.g., Local: http://localhost:<port>/) and connect to the port the server actually bound to. Most frameworks emit this line:
- Vite:
➜ Local: http://localhost:3003/ - Next.js:
- Local: http://localhost:3001 - webpack-dev-server:
Project is running at http://localhost:8081/ - Create React App:
Local: http://localhost:3001
Environment
- Claude Code version: latest (May 2026)
- OS: macOS
- Framework: Vite 5.4
- Context: Common in worktree setups where the main repo already occupies port 3000
Workaround
Set a fixed port in launch.json that doesn't conflict with other servers. This works but is fragile and defeats the purpose of framework-level auto-port detection.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗