Port janitor · v1.3.9

Your ports have squatters.Kick them out.

Kickoutchi shows which process owns each open TCP/UDP port, explains why a port won't bind, watches ports change hands, and terminates stale port-owning processes safely. Use the guided TUI or the script-friendly CLI.

Install Kickoutchi Read the docs GitHub ↗

linux · macos · windowstwo binaries: kickoutchi & kickMIT

SCAN

KICK

INSPECT

◆kick inspect --port 3000◆SQUATTER FOUND◆kick kill --pid 18422 --tree◆SIGTERM → 3 procs◆port :3000 free ✓◆exit 0◆kick why 3000◆verdict: owned◆kick watch --json◆bind → release → replacement◆label: web dev◆kick list --json◆no guessed PIDs◆PID 1 is off-limits◆tree scope: opt-in◆kick kill --port 5173◆confirmed, always

01 · Inspect first

See the whole family before you swing the boot.

A stale dev server is rarely one process. kick inspectshows ancestors, descendants, and the process group in read-only mode. It then tells you the exact command for the scope you choose. Nothing dies until you type it.

01Inspect the PID or port. See who spawned it and what it spawned.
02Pick a scope: one process, the tree, or the Unix process group.
03Type the scope word to confirm. Kickoutchi verifies the port is really free.

kick • clearing a dev-server tree

$ kick inspect --port 3000
Target: PID 18422 (node)
  Ports: TCP 127.0.0.1:3000
  Process group: 18400
Ancestors (nearest first):
  PID 18190 (pnpm); pnpm dev
Tree (3 processes):
  PID 18422 (node) [TCP 127.0.0.1:3000]
    PID 18431 (vite)
    PID 18444 (esbuild)
To terminate this tree: kick kill --pid 18422 --tree
$ kick kill --pid 18422 --tree
Terminate process tree from PID 18422 (node)
Scope: tree (3 processes)
Ports: TCP 127.0.0.1:3000
  PID 18422 (node)
    PID 18431 (vite)
    PID 18444 (esbuild)
Type tree to terminate all 3 processes, or press Enter to cancel: tree
sent SIGTERM to 3 process(es) in the tree rooted at PID 18422 (node)
confirmed target ports are no longer visible

02 · Ask why

kick • why is :3000 refusing me?

$ kick why 3000
WHY port=3000 protocols=TCP addresses=127.0.0.1,::1 snapshot=partial
scope kind=current_network_namespace identifier=net:[4026531833]
tcp://127.0.0.1:3000 verdict=owned certainty=proven label=web dev
  probe=address_in_use raw_os_error=98
  evidence code=visible_verified_owner source=linux_procfs
    PID 18422 (node) owned the endpoint at snapshot capture
  evidence code=exact_bind_address_in_use source=bind_probe
    the exact bind probe reported that the address is in use
tcp://[::1]:3000 verdict=bindable_now certainty=proven label=-
  evidence code=exact_bind_succeeded source=bind_probe
    the exact bind probe succeeded
aggregate_exit_code=3

"Address already in use" is not an explanation.

kick why takes one native snapshot, then actually attempts the bind and immediately closes it. Occupied, permission denied, address unavailable, and unsupported are four different answers, and each verdict shows the evidence and certainty it rests on.

verdict=owned; the snapshot named the owner and the probe was refused.
verdict=bindable_now; the exact bind succeeded. That is a fact about one moment, not a reservation.
certainty= is attached to the specific claim carrying it, so a guess never reads like a proof.

Watch & Why

03 · Two ways in

Two ways to clear the swamp

Open the TUI when you want to look around. Reach for the CLI when you already know the target.

The swamp tour

Guided TUI

Run either binary with no command to open the terminal UI. Browse, search by label or address, sort, inspect details, and use x/X for one PID or t/T for Linux/macOS tree cleanup.

shell

kickoutchi

Explore the TUI

The swamp shortcut

Scriptable CLI

Print ports as a table or stable JSON, ask why an endpoint won't bind, watch binds and releases as NDJSON, and choose process, tree, or Unix group scope with a fixed exit-code contract.

shell

kick list --filter 'label:web family:ipv4'

Explore the CLI

04 · The arsenal

A small tool that takes ports seriously

Practical first, playful second. Everything here is real behaviour.

See every open port

Lists listening TCP sockets and bound UDP sockets using native collectors • no scraping ss, netstat, or lsof.

Know what owns it

Shows PID, process name, parent, path, command line, bind scope, and permission status whenever the OS lets it through.

Name your ports

Label exact endpoints or protocol-and-port wildcards in config. Labels show up in the CLI, wide TUI tables, search, filters, JSON, watch events, and why output.

Ask why a port won't bind

kick why PORT combines one snapshot with a real bind probe to separate occupied, permission denied, unavailable, and unsupported. It shows the evidence behind each verdict.

Watch ports change hands

kick watch streams bind, release, replacement, and collection-gap events from bounded polling, as terminal output or one versioned NDJSON object per line.

Tree and group cleanup

Opt in to --tree for descendants when a stale dev stack has more than one PID. POSIX process-group cleanup stays Linux/macOS-only.

Inspect before you kick

Read-only inspect shows ancestors, descendants, siblings, command lines, ports, and scoped kill hints. Linux/macOS also show process groups.

TUI or CLI

Open the guided terminal UI for a tour of open ports, or drive the script-friendly CLI when you already know the target.

Safe by default

Every termination is confirmed. Unix scoped kills freeze and verify; Windows tree kill contains via Job Objects; ambiguous ports are never guessed.

Linux, macOS, Windows

Native collection per OS. Linux/macOS support tree and group scope; Windows supports inspect and CLI tree kill, with --group unavailable.

Export the full picture

list --snapshot-json emits one bounded, scope-qualified observation: every native TCP state, owner identity, completeness, and the evidence gaps behind it.

Docker-aware

Explains Docker-owned or partial-metadata ports in details when the Docker CLI is available. Docker owners are protected by default; Docker itself is optional.

Filters & sorting

Narrow the table with port:, proto:, scope:, protected:, parent:, label:, address:, scope_id:, and family: filters, then sort by port, pid, protocol, process, parent, or scope.

Built for scripts

Four versioned output contracts, fixed exit codes, --yes gates that re-check fresh scope, and explicit CLI-only inspect/group commands make automation predictable.

New in v1.3.9

Leaner binaries, one refusal language

Kickoutchi 1.3.9 tightens internal safety semantics, adds bounded parser campaigns and release provenance, and ships smaller binaries without a measured performance regression.

Read the changelog Full benchmark

one refusal language: Windows and Unix tree handling now share refusal causes and exit classifications; CLI and TUI wording stays consistent without hiding interface-specific recovery details.
measured, then leaner: A 24,000-execution Linux comparison found no meaningful regression, then stripped distribution binaries cut each x86_64 executable by 18.72%.
attested releases: Every native archive and installer is validated before publication, attested with GitHub provenance, downloaded again, verified, and exercised through the public release.
bounded parser campaigns: Pure configuration, Linux process-data, and archive-path fuzz targets run on a pinned toolchain; saved regression corpora replay in ordinary CI.

Linux performance snapshot

3,000 observations per build and workload · 24,000 executions · 0 errors or timeouts

x86_64 binaries −18.72%

Workload	p50	p99	p99 vs 1.3.8
Cold startup	1.145 ms	1.222 ms	+0.27%
Warm startup	1.146 ms	1.215 ms	-0.09%
list	12.799 ms	22.435 ms	+3.84%
list --json	12.774 ms	21.275 ms	-0.30%

Same-machine directional snapshot on an AMD Ryzen AI Max+ 395 running Linux. The complete release archive also fell by 11.29%; see the full report for methodology and caveats.

05 · Guardrails

Safe by default

Terminating the wrong process is the scary part. Kickoutchi treats it that way: lots of guardrails, no silent surprises.

How termination stays safe

00Every termination is confirmed. --yes still prints the banner, warnings, and fresh-scan refusals.
01PID 0, PID 1, Kickoutchi's own PID, and Windows PID 4 are blocked outright.
02kill --port refuses ambiguous ports instead of guessing which PID to hit.
03Protected processes, including Docker owners, require typing the PID or process name to confirm.
04Tree scope is opt-in, typed, and bounded; group scope stays Linux/macOS-only.
05Unix scoped kills freeze first; Windows tree kill uses Job Object containment.
06Names, paths, and status text are sanitized against control, ANSI, bidi, and zero-width tricks.

06 · Get it

Install in one line

Linux, macOS, and Windows get installers, archives, inspect, and explicit tree cleanup. Group scope stays Unix-only.

Linux & macOS

$ curl --proto '=https' --tlsv1.2 -LsSf \
    https://github.com/nuggocto/kickoutchi/releases/latest/download/kickoutchi-installer.sh \
    | sh

All install methods

Platforms & packages

Honest status, kept compact.

Linux

Native /proc collection with pidfd-backed tree/group kill and inspect.

macOS

Native libproc / sysctl collection with tree/group kill and inspect.

Windows

Native IP Helper listing, inspect, single-process kill, and CLI tree kill via Job Objects.

AvailableInstaller, Release archives, Cargo, Nix flake, AUR, Homebrew, Scoop

CLEAR THE SWAMP.

Install Kickoutchi, run it once with no arguments, and see the processes and process families using your local ports.

Install Kickoutchi GitHub

$ kickoutchi