port-saver

port-saver

Claude Code plugin that automatically detects port conflicts before server startup commands or config file writes. When a conflict is found, it blocks the action and suggests the nearest available port.

Installation

Option 1: Plugin (recommended)

In Claude Code, run:

/plugin marketplace add gtpgg1013/gtpgg1013-plugins
/plugin install port-saver@gtpgg1013-plugins
/reload-plugins

Option 2: Manual

Clone this repo and add the hook to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/port-saver/port-saver.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

How It Works

1. Intercepts Bash, Write, and Edit tool calls via Claude Code's PreToolUse hook
2. Bash: Detects server start commands, extracts ports from the command or project config files, checks lsof for conflicts
3. Write/Edit: Detects config file writes, extracts ports from the content being written
4. If a port is in use by a different project, blocks the action (exit 2) and suggests an alternative
5. If the same project is restarting, allows it through (same-project bypass)

Supported Server Commands

Ecosystem	Commands
Node.js	npm run dev/start/serve, npm start, yarn dev/start/serve, pnpm dev/start/serve
npx	npx serve/http-server/next/vite/nuxt/expo
Bun	bun run dev/start/serve, bun dev, bunx
Deno	deno serve/run/task
Frameworks	next dev, nuxi dev, astro dev, gatsby develop, remix dev, ng serve, storybook dev
Bundlers	webpack serve, webpack-dev-server
Python	python manage.py runserver, python -m http.server/flask/uvicorn, flask run, gunicorn, uvicorn, streamlit run, gradio, jupyter notebook/lab, sanic
Ruby	rails server/s, bundle exec puma/thin/unicorn/rails, puma, thin start, unicorn
PHP	php -S, php artisan serve, symfony serve/server:start
Java	java -jar, ./gradlew bootRun, ./mvnw spring-boot:run, mvn/gradle bootRun
.NET	dotnet run/watch
Go	go run
Rust	cargo run
Docker	docker-compose up, docker compose up, docker run
SSG	hugo server/serve, jekyll serve/s, hexo server/s, mkdocs serve, pelican --listen, eleventy --serve
Other	caddy run/start, expo start, flutter run, consul agent

Supported Config Files

File	Port Pattern
.env, .env.local, .env.development, .flaskenv	PORT=N, *_PORT=N
docker-compose.yml, compose.yml	"N:N" port mappings
package.json	--port N, -p N in scripts
angular.json	"port": N
vite.config.*, next.config.*, nuxt.config.*	port: N
astro.config.*, vue.config.*, remix.config.*, svelte.config.*	port: N
webpack.config.*	port: N
application.properties	server.port=N
application.yml / application.yaml	port: N
Procfile	--port N, -p N, --bind :N

Port Extraction from Commands

Extracts ports from these CLI patterns:

• PORT=3000 npm start (env var)
• --port 3000 / --port=3000 / -p 3000
• python -m http.server 8080
• python manage.py runserver 0.0.0.0:8000
• docker run -p 3000:80
• php -S localhost:8000
• gunicorn --bind 0.0.0.0:8000 / -b :8000
• --server.port 8501 / --server.port=8501
• -Dserver.port=8081 (Spring Boot)
• dotnet run --urls http://*:5100
• mkdocs serve --dev-addr=0.0.0.0:8000
• flutter run --web-port 8080

Requirements

• jq — JSON parsing (brew install jq on macOS)
• lsof — port checking (built-in on macOS and Linux)

License

MIT