snipe-port

Kill processes on a port, but only if they belong to the same project.

Unlike kill-port or fkill, snipe-port checks that the process shares the same working directory or git repo (including worktrees) before killing it. This prevents accidentally killing unrelated processes during development.

Install

npm i -g snipe-port

Usage

CLI

snipe-port 3000           # kill process on port 3000 (if same project)
snipe-port 3000 8080      # multiple ports
snipe-port -p 3000        # --port flag
snipe-port -9 3000        # force kill (SIGKILL)
snipe-port --udp 3000     # target UDP instead of TCP

Programmatic API

import { snipePort } from 'snipe-port'

// Kill process on port 3000 (returns array of killed PIDs)
const killed = await snipePort(3000)

// Force kill with SIGKILL
const killed = await snipePort(3000, { signal: 'SIGKILL' })

// Target UDP
const killed = await snipePort(3000, { method: 'udp' })

How it works

1. Find PIDs on the given port using lsof (macOS/Linux)
2. Resolve working directory of each process (lsof -d cwd on macOS, /proc/PID/cwd on Linux)
3. Check project membership — the process is considered part of the same project if:
   • Its working directory matches the current directory, OR
   • It shares the same git repository root (including git worktrees)
4. Kill only matching processes with SIGTERM (or SIGKILL with -9)

Why?

During development you often restart servers and need to free up a port. Tools like kill-port will kill any process on that port — including a database, another project's dev server, or a production process you didn't mean to touch.

snipe-port scopes the kill to your current project, so it's safe to use without thinking twice.

Options

| Flag | Description | |------|-------------| | -p, --port <port> | Specify port(s) to kill | | -9, --force | Force kill with SIGKILL | | --udp | Target UDP instead of TCP | | -h, --help | Show help | | -v, --version | Show version |

Requirements

• Node.js >= 14
• macOS or Linux (lsof required)

License

MIT