steal-port: Reclaim Ports from Coding Agents

Sometimes coding agents like Claude Code leave a service running that you want to run yourself. steal-port is a small script you can add to your run command to easily reclaim a port and switch out an app or service for your own.

Usage

The tool supports three invocation patterns:

# Use port from .env.local or .env file
steal-port

# Specify port as positional argument
steal-port 3000

# Named parameter formats
steal-port --port 3000
steal-port -p 3000

How It Works

  1. Checks for an explicitly provided port argument first
  2. Searches for PORT= variable in .env.local file
  3. Falls back to checking .env file if .env.local lacks the port
  4. Terminates with an error if no port configuration exists
  5. Identifies and terminates the process occupying that port
  6. Completes successfully regardless of whether a process required termination

Integration with npm Scripts

The most common pattern is to prefix your dev commands:

{
  "scripts": {
    "dev": "steal-port && vite",
    "watch": "steal-port && nest start --watch"
  }
}

This ensures the port is free before launching your development server.