Open source project / 2026
PortTree
A zero-dependency Python CLI for resolving port collisions, zombie process trees, and Docker socket masks in local development and CI.
Context
EADDRINUSE crashes and orphaned sockets disrupt development workflows and CI suites when servers fail to unbind ports cleanly.
The problem
A blind 'kill -9 <PID>' often fails because supervisor processes respawn workers immediately, or the socket is masked behind docker-proxy.
Approach
PortTree parses /proc/net/tcp and socket inodes on Linux, queries iphlpapi via ctypes on Windows, and traces the complete process tree up to init.
System architecture
Zero third-party dependencies; direct OS kernel syscalls and memory tables provide instant socket-to-process attribution across Linux, Windows, and macOS.
Key decisions
Implements graceful two-phase termination (SIGTERM followed by SIGKILL timeout) and machine-readable JSON output for CI pre-flight checks.
Outcome
Available on PyPI as porttree. It provides ASCII tree inspection, port availability assertions, and safe socket cleanup without requiring psutil.
Learnings
Direct kernel interface parsing eliminates compilation overhead and wheel building issues in minimal Alpine and CI containers.