Use when about to start a dev server, run e2e tests, or connect to a database — proactively detects resource conflicts from other running processes and silently adapts to avoid collisions
Multiple Claude instances working on the same project will collide on ports, databases, and browser instances. This skill teaches proactive detection and silent adaptation — check what's in use, pick something else, report what you chose.
Core principle: Observe system state, adapt silently, report in terminal. No coordination files, no lock files, no shared state.
Before any of these actions, run the detection checks:
next dev, npm run dev)Before starting a dev server:
lsof -i :3000 -t 2>/dev/null
If occupied, scan upward (3001, 3002, ...) until a free port is found. Start with:
PORT=<free_port> next dev
Playwright with webServer config:
baseURLPlaywright without webServer (external server):
BASE_URL=http://localhost:<free_port> npx playwright test
Hardcoded baseURL in Playwright config (common case):
Most configs hardcode baseURL: 'http://localhost:3000' instead of reading from env. If so, BASE_URL=... won't work. Flag the user with this exact fix:
Your
playwright.config.tshas a hardcodedbaseURL. Please update it to:baseURL: process.env.BASE_URL || 'http://localhost:3000'This lets me override the port via env var without modifying config files.
Before running tests that write to or assert against the DB:
parallel_<epoch>_ (e.g., parallel_1741234567_)psql "$DATABASE_URL" -c "CREATE SCHEMA parallel_1741234567_;"
PGOPTIONS="--search_path=parallel_1741234567_" npx supabase db push
SUPABASE_SCHEMA=parallel_1741234567_ npx playwright test
psql "$DATABASE_URL" -c "DROP SCHEMA parallel_1741234567_ CASCADE;"
Before running Playwright tests:
TMPDIR=/tmp/playwright_<epoch> npx playwright test
Or more targeted — isolate only the browser path:
PLAYWRIGHT_BROWSERS_PATH=/tmp/pw_browsers_<epoch> npx playwright install chromium
PLAYWRIGHT_BROWSERS_PATH=/tmp/pw_browsers_<epoch> npx playwright test
After adapting, report once and move on:
⚡ Parallel isolation:
Dev server: port 3005 (3000 was in use)
DB schema: parallel_1741234567_
Playwright: /tmp/playwright_1741234567
Only report resources that were actually adapted. If nothing conflicted, say nothing.
| Resource | Detection | Adaptation | Cleanup |
|---|---|---|---|
| Dev server port | lsof -i :<port> | PORT=<next_free> | None needed |
| Supabase DB | Check if tests write/assert | parallel_<epoch>_ schema | Drop schema after tests |
| Playwright browser | Check for lock contention | TMPDIR or PLAYWRIGHT_BROWSERS_PATH | Temp dir auto-cleaned |
playwright.config.ts or next.config.js creates git conflictsBASE_URL to Playwright.Never:
Always: