port-manager
A helper skill for agents to intelligently manage ports when starting development servers. Avoid unnecessary restarts by checking if the server is already running.
When to use
ALWAYS refer to this skill when the user asks to:
- start the dev server / development server
- run the dev server / development server
- start the server / run the server
- start the app / run the app
- execute npm run dev / pnpm dev / yarn dev
- execute npm run start / pnpm start / yarn start
- execute vite / next dev / nuxt dev
- 개발서버 실행 / 개발 서버 시작 / 서버 켜줘
- 서버 시작 / 실행 / 서버 띄워줘
- npm run dev 해줘 / pnpm dev / yarn dev
- dev 서버 실행 / 실행해줘 / 켜줘
Also refer when:
- About to execute any command that binds to a port
- Encountering "port already in use" error
Instructions
Before Starting Dev Server
When the user asks to start a dev server, ALWAYS check the port first:
- Identify the project's port (in order of priority):
- Check framework config: vite.config.ts, next.config.js, nuxt.config.ts - Check package.json scripts: "dev", "start", "preview" - Use defaults if not found: - Next.js/Nuxt/Rails/CRA: 3000 - Vite: 5173 - Django/Flask: 8000 - Express: 3000 (or check app.listen()) - http-server/npx serve: 8080 - live-server: 5500 - webpack-dev-server: 8080
- Check if the port is already occupied
lsof -i:<port> - Handle the result If port is FREE: If port is occupied by SAME PROJECT: If port is occupied by DIFFERENT PROCESS:
- Start the dev server - Confirm success with URL (e.g., "✓ Server running at http://localhost:3000") - How to verify: Check if command path contains current project directory - Example: /Users/user/my-app/node_modules/.bin/vite = same project - Skip starting, inform user: "✓ [Project] dev server is already running at http://localhost:3000" - Do NOT start another instance - Ask user: "⚠️ Port 3000 is occupied by [process details]. Options: 1. Kill it and start [project] server 2. Skip and keep existing What would you prefer?"
Platform Notes
macOS/Linux/WSL:
- Check port:
lsof -i:<port> - Kill process:
kill -9 <PID>
Windows native:
- Check port:
netstat -ano | findstr:<port> - Kill process:
taskkill /PID <PID> /F