Developers relying on Git worktrees often encounter a frustrating silent failure: a development server answers on the expected port, but the process is actually running from a different checkout. On October 3, 2026, developer Arthur031221 released worktree-port-check, a new utility designed to diagnose this exact mismatch by comparing the terminal’s current directory with the working directory of every process listening on a specific TCP port.

How The Diagnostic Works

The tool operates by querying lsof to identify TCP listeners on the selected port. It then inspects the current working directory (cwd) of each visible process and asks Git to resolve the checkout root and common directory at that path. The report categorizes results into four distinct states: a matching root confirms the correct checkout; a different root with the same Git common directory indicates another linked worktree in the same repository; a different common directory signals a completely different repository; and a cwd outside Git receives a separate flag. Crucially, branch names are included for context but do not determine the comparison logic.

Installation And Usage Constraints

worktree-port-check requires Node.js 20 or newer, Git, and lsof, currently supporting macOS and Linux environments. Users can invoke the tool via npx with the command npx --yes --package=github:Arthur031221/worktree-port-check worktree-port-check 3000. The utility provides structured output via the --json flag and uses exit codes to signal status: exit code 1 indicates a visible listener belongs to another checkout, while exit code 4 means the inspection lacked sufficient information for a complete result.

Known Limitations And Edge Cases

The author explicitly notes that process cwd is not definitive proof of which files a server loaded earlier or which code it is currently serving. A process may change directories after startup, and operating system permissions can hide listeners or their cwd from the inspection. The tool reports these limits rather than attempting to send requests to the application or forcibly stopping processes. Git commands within the tool run without inherited GIT_* environment variables, and optional index locks are disabled to prevent interference.

Key Takeaways

  • The tool distinguishes between linked worktrees in the same repo versus entirely different repositories.
  • It relies on lsof and process cwd inspection, not HTTP requests to the dev server.
  • Exit codes provide CI-friendly feedback: 1 for mismatch, 4 for inconclusive.
  • Requires Node.js 20+ and works on macOS and Linux only.

The Bottom Line

While it cannot prove exactly what code is running, worktree-port-check is a vital diagnostic for eliminating the confusion of stale Git worktrees during development. This tool fills a critical gap for developers who frequently switch contexts, offering immediate clarity on which process owns a port without needing to manually trace PIDs and directories.