Repolode
Submit
pranshuparmar

pranshuparmar/witr

A CLI and TUI that traces any process, port, container, or file back to the chain of systems that started it.

View on GitHubWebsite
Stars
22,720
Forks
892
Open issues
2
Last commit
yesterday

What is it?

witr answers the question "why is this running?" for a process, a listening port, a container, or a file held open. Tools like ps, lsof, ss and docker ps show what is running, but not how it got started. witr walks the parent chain and supervisors (systemd, launchd, PM2, cron, SSH sessions, tmux, container runtimes) to show the sequence of systems responsible for the process.

Running witr with a name, --pid, --port, --file or --container prints a narrative report with the ancestry chain, the source that started the process, working directory, git branch, sockets, and warnings such as running as root or listening on a public interface. Output can be short, tree-style, verbose, or JSON with documented exit codes for scripts and CI. Running it with no target opens an interactive TUI with tabs for processes, ports, containers and file locks, plus signal and renice actions on Unix.

The project is written in Go and ships as a single binary for Linux, macOS, Windows and FreeBSD, with several package manager options.

Key features

  • 01Traces the parent chain and supervisor (systemd, launchd, PM2, cron, SSH) behind a process.
  • 02Looks up targets by process name, PID, listening port, open file, or container.
  • 03Covers Docker, Podman, nerdctl, Kubernetes/crictl, Incus, LXC, LXD and FreeBSD jails.
  • 04Provides an interactive TUI with processes, ports, containers and file locks tabs.
  • 05Outputs human-readable reports, short or tree views, or JSON with documented exit codes.

Use cases

  • Finding out what is holding a port when a dev server fails with 'address already in use'.
  • Investigating an unknown or stuck process during an incident on a Linux server.
  • Checking which Compose service or container owns a running port.
  • Letting AI coding agents diagnose port and process conflicts via JSON output.

Quick start

  1. 1

    Install via the Unix install script

    Install with the official instructions in the README
  2. 2

    Or install via Homebrew

    brew install witr
  3. 3

    Or install from Go source

    go install github.com/pranshuparmar/witr/cmd/witr@latest

Things to know

  • Installation options differ by platform, and community packages may lag GitHub releases.

Topics

#cli#tui#process-management#troubleshooting#devops#observability#containers#go#docker#freebsd

FAQ

What is witr?
A CLI and TUI that traces any process, port, container, or file back to the chain of systems that started it. witr answers the question "why is this running?" for a process, a listening port, a container, or a file held open. Tools like ps, lsof, ss and docker ps show what is running, but not how it got started. witr walks the parent chain and supervisors (systemd, launchd, PM2, cron, SSH sessions, tmux, container runtimes) to show the sequence of systems responsible for the process.
Is witr free to use? What license does it have?
witr is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is witr still maintained?
Actively maintained. The last commit to witr was on Oct 19, 2026.
What can I use witr for?
Finding out what is holding a port when a dev server fails with 'address already in use'. Investigating an unknown or stuck process during an incident on a Linux server. Checking which Compose service or container owns a running port. Letting AI coding agents diagnose port and process conflicts via JSON output.
How do I install witr?
Install via the Unix install script Or install via Homebrew: brew install witr Or install from Go source: go install github.com/pranshuparmar/witr/cmd/witr@latest
Where can I get witr?
The source code and installation instructions are on GitHub: https://github.com/pranshuparmar/witr

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects