Improvement: Diagnose port conflicts by checking if the project itself is already running

Resolved 💬 2 comments Opened May 27, 2026 by mine1212design-blip Closed Jul 11, 2026

Summary

When a port conflict is detected during preview_start, Claude Code reports "port is in use by another process" without further investigation. In practice, the conflicting process is often the same project already running from a previous session or terminal.

Current Behavior

  1. preview_start detects port 3000 is in use
  2. Reports: "Port 3000 is in use by another process"
  3. Assigns a fallback port (e.g. 60138) and starts a second instance
  4. User cannot access the preview — they don't realize the app was already running

Expected Behavior

  1. Port conflict detected
  2. Automatically inspect the conflicting process (PID, command line, executable path)
  3. If it matches the current project directory → tell the user: "This project is already running on port 3000. Open http://localhost:3000"
  4. Skip starting a duplicate instance

Suggested Steps

  1. Get PID using the port (netstat / lsof)
  2. Get full command line of that PID
  3. Compare path against current project directory
  4. If match: show "Already running" + URL
  5. If no match: report the foreign process name and path

Context

  • OS: Windows 10
  • Claude Code version: v2.1.152
  • Reproduction: Run npm run dev in a terminal, then ask Claude Code to start the same project via preview_start

Impact

Non-engineers are confused by the port conflict error and cannot easily tell whether to stop a process or just open a browser tab.

---

Reported via Claude Code by a non-engineer user.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗