Port Management

Detect framework, find a free port, and start the dev server with the correct port flag. Resolves port conflicts automatically.

Progress Checklist

Port Management Progress:
- [ ] Step 1: Parsed arguments (mode, preferred port)
- [ ] Step 2: Scanned ports for current usage
- [ ] Step 3: Detected framework from project files
- [ ] Step 4: Found available port
- [ ] Step 5: Started server with correct flag

Step 1: Parse Arguments

Modes:

• (default) — detect framework, find free port, start server

• --scan

  — show what's running on ports 3000–3100

• --find

  — just report next free port (no server start)

• --kill <port>

  — kill the process occupying a specific port (with safety checks, see Step 2)

Optional arguments:

• --port <number>

  — preferred starting port (overrides framework default)

Step 2: Scan Port Usage

Show what's currently occupying ports in the project's default range.

macOS/Linux:

lsof -iTCP -sTCP:LISTEN -nP 2>/dev/null | grep -E ':(3[0-9]{3}|4[0-3][0-9]{2}|4321|5[0-1][0-9]{2}|5173|8[0-9]{3})' | sort -t: -k2 -n

Windows (PowerShell):

Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -ge 3000 -and $_.LocalPort -le 9000 } | Sort-Object LocalPort | Format-Table LocalPort, OwningProcess, @{N='Process';E={(Get-Process -Id $_.OwningProcess).ProcessName}}

Detect platform: Check if

lsof

command -v lsof

netstat -ano

Get-NetTCPConnection

If mode is

--scan

If mode is

--kill <port>

Never kill blindly. First identify the process on the port:

macOS/Linux:

lsof -iTCP:<port> -sTCP:LISTEN -nP 2>/dev/null

Windows (PowerShell):

Get-NetTCPConnection -LocalPort <port> | ForEach-Object { Get-Process -Id $_.OwningProcess } | Format-Table Id, ProcessName, Path

Protected processes — never kill these:

• Browsers:

  firefox

  ,

  chrome

  ,

  safari

  ,

  msedge

  ,

  brave

  ,

  arc

  ,

  opera

• System services:

  launchd

  ,

  systemd

  ,

  svchost

  ,

  WindowsServer

• Databases:

  postgres

  ,

  mysqld

  ,

  mongod

  ,

  redis-server

• Docker:

  docker

  ,

  containerd

  ,

  com.docker.backend

If the process matches a protected name, tell the user what's on the port and do not kill it. Suggest they close the relevant tab/connection manually or pick a different port instead.

Only kill dev server processes (e.g.

node

python

ruby

dotnet

cargo

go

macOS/Linux:

kill <pid>

Windows (PowerShell):

Stop-Process -Id <pid>

Prefer

kill

kill -9

kill -9

Step 3: Detect Framework

Check project config files to determine the framework. Search in order of specificity:

Check these files (stop at first match):

next.config.*

nuxt.config.*

vite.config.*

svelte.config.*

angular.json

astro.config.*

manage.py

app.py

wsgi.py

Cargo.toml

go.mod

*.csproj

*.sln

Gemfile

rails

If no specific config found, check

package.json

# Read package.json and check dependencies + devDependencies for:
# - "react-scripts" → CRA
# - "next" → Next.js
# - "nuxt" → Nuxt
# - "vite" → Vite
# - "@angular/core" → Angular
# - "astro" → Astro
# - "express" → Express
# - "fastify" → Fastify
# - "hono" → Hono
# - "remix" → Remix
# - "@sveltejs/kit" → SvelteKit

For Vite projects, also check

vite.config.*

• @sveltejs/kit

  plugin → SvelteKit

• @remix-run/dev

  plugin → Remix
• Otherwise → plain Vite

Detect package manager (for Node.js projects):

if [ -f "bun.lockb" ]; then echo "bun"
elif [ -f "pnpm-lock.yaml" ]; then echo "pnpm"
elif [ -f "yarn.lock" ]; then echo "yarn"
else echo "npm"
fi

Also check for a

dev

start

package.json

Step 4: Find Available Port

Starting from the framework's default port (or

--port

macOS/Linux:

check_port() {
  lsof -iTCP:"$1" -sTCP:LISTEN -nP 2>/dev/null | grep -q ":$1" && return 1 || return 0
}

find_free_port() {
  local port="${1:-3000}"
  while ! check_port "$port"; do
    port=$((port + 1))
  done
  echo "$port"
}

Windows (PowerShell):

function Find-FreePort($start = 3000) {
  $port = $start
  while (Get-NetTCPConnection -LocalPort $port -ErrorAction SilentlyContinue) { $port++ }
  return $port
}

Framework default ports:

If mode is

--find

Step 5: Start Server

Use the detected framework and package manager to start the dev server on the available port.

Port flag per framework

{pm} run dev

-p <port>

-- -p <port>

{pm} run dev

-- --port <port>

{pm} run dev

-- --port <port>

{pm} run start

PORT=<port>

{pm} run dev

-- --port <port>

{pm} run start

ng serve

-- --port <port>

{pm} run dev

PORT=<port>

python manage.py runserver

0.0.0.0:<port>

flask run

--port <port>

uvicorn main:app

--port <port>

bin/rails server

-p <port>

dotnet run

--urls http://localhost:<port>

go run .

PORT=<port>

cargo run

PORT=<port>

{pm}

npm quirk: When passing flags through npm scripts, use

--

npm run dev -- -p 3001

--

Before starting: Tell the user which framework was detected, which port will be used, and the exact command being run.

Scripts with hardcoded ports

Before appending port flags, read the

dev

start

package.json

-p

--port

PORT=

If a port is already in the script:

1. Tell the user what port is configured and where (e.g.

   "dev": "next dev -p 4000"

   )
2. Check if that port is available — if so, just run the script as-is without extra flags
3. If that port is occupied, do not blindly append another port flag — most frameworks ignore duplicates or behave unpredictably with two port args
4. Instead, suggest the user either:
   • Temporarily edit the script to use the new port
   • Use an env var override if the framework supports it (e.g.

     PORT=3001 pnpm run dev

     for Express/CRA)
   • Run the underlying command directly (e.g.

     pnpm next dev -p 3001

     instead of

     pnpm run dev

     )

Error Handling

Port conflict in default mode:

• Never kill processes. Always increment to the next free port.
• Tell the user which port was occupied and what port was chosen instead.

--kill

• The process may take a moment to release the port. Wait 3 seconds and re-check.
• If still occupied after SIGTERM, ask the user before escalating to

  kill -9

  .

No framework detected:

• Tell the user no framework was identified.
• List what was checked.
• Ask which command they'd like to run.

Dev script not found in package.json:

• Check for common script names:

  dev

  ,

  start

  ,

  serve

  .
• If none found, ask the user for the start command.

Examples

Default: Start dev server

User: start the dev server

1. Scan ports → port 3000 in use by another Next.js instance
2. Detect framework → Next.js (found

   next.config.ts

   )
3. Detect package manager → pnpm
4. Find free port → 3001
5. Run:

   pnpm run dev -- -p 3001

Scan mode

User: /managing-ports --scan

Output: Table of ports 3000–3100 showing PID, process name, and port.

Find mode

User: /managing-ports --find --port 8080

Output: "Port 8080 is in use. Next available: 8081"

Kill mode

User: /managing-ports --kill 3000

Output: "Killed process 12345 (node) on port 3000"