Noureddine RAMDI / witr: tracing the full causality chain of running processes in Go

Created Sun, 03 May 2026 11:08:03 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
952 Words
github-stars go cli process-tracing systemd containers tui

pranshuparmar/witr

Understanding why a particular process, service, or port is running on your system can quickly become a frustrating manual exercise. You run ps to get process details, then lsof or ss to check open files and sockets, and finally dive into systemctl or docker ps to find the supervisor or container responsible. witr collapses this entire mental overhead into a single command that traces the full causality chain of a running process, revealing how it ended up running from kernel to user space.

what witr does and its architecture

witr is a command-line tool implemented in Go, designed to answer the question “why is this running?” by tracing the entire causality chain of any running process, service, or port binding. Unlike traditional tools like ps, lsof, or ss that show a snapshot of state, witr correlates multiple sources of process supervision — including systemd units, containers, supervisors, shells, and parent processes — to provide a comprehensive explanation of how a process ended up running.

The tool ships as a static binary that supports Linux, macOS, FreeBSD, and Windows, making it truly cross-platform. This portability is a strong plus when you manage heterogeneous environments.

Architecturally, witr hooks into system APIs and process trees to build a causality graph. It understands different supervision layers, such as systemd units and container runtimes, and merges their information with the classic parent process chain. This multi-source correlation is what sets witr apart.

Beyond the command-line interface, witr includes an interactive TUI (terminal user interface) mode that allows real-time exploration of processes and their causal chains, enhancing the developer and sysadmin experience during live investigations.

what distinguishes witr: tracing causality, not state

The key strength of witr lies in its ability to replace a fragmented debugging workflow with a unified, causality-focused view. Typically, to find out why a process is running, you have to combine outputs from:

  • ps to get the process tree
  • lsof or ss to identify open files and sockets
  • systemctl to check systemd unit status
  • docker ps or container runtimes to check containerized processes

witr collapses all this into one command, tracing upstream from a given process or port to reveal the chain of triggers that launched it. This saves time and reduces cognitive load.

The code reflects a careful design to handle multiple supervision systems simultaneously. It identifies supervisors, containers, and systemd units and merges them logically with the parent process chain. This multi-layer correlation is not trivial since each supervision system has its own metadata and hierarchy.

Tradeoffs include the complexity of keeping up with evolving container runtimes and system managers, which can affect the accuracy of causality tracing in edge cases. Also, while witr covers many common supervision systems, it might not fully support highly custom or obscure setups.

The codebase benefits from Go’s static compilation model, producing a single binary with zero runtime dependencies. This simplifies deployment and use in production environments.

The interactive TUI mode is a practical addition, letting users explore causality chains visually and drill down into details without rerunning commands.

quick start with witr

The installation process is straightforward and well-documented, offering multiple options depending on platform and preference.

Unix (Linux, macOS & FreeBSD)

curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash

This script detects your OS and CPU architecture, downloads the latest binary and man page, and installs them to /usr/local/bin/witr and /usr/local/share/man/man1/witr.1 respectively.

Windows (PowerShell)

irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex

This downloads the latest release zip, verifies the checksum, extracts witr.exe to %LocalAppData%\witr\bin, and adds it to your user PATH.

Other options include:

  • Installing via the Aqua package manager:
aqua i pranshuparmar/witr
  • Using Brioche on Linux:
brioche install -r witr

  • Installing native packages (.deb, .rpm, .apk) from GitHub releases using standard package managers.

  • Installing from source with Go:

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

Once installed, you can run witr with various flags or enter the interactive mode to begin tracing processes.

verdict: who should use witr

witr is a solid tool for sysadmins, developers, and SREs who frequently need to understand the why behind running processes on their systems. It streamlines a common investigative workflow by correlating process, supervision, and container information into a single view.

Its cross-platform static binary and minimal dependencies make it easy to deploy even in complex environments. The interactive TUI mode is a nice touch for live troubleshooting.

Limitations include possible edge cases with less common supervision setups or rapidly evolving container technologies. Also, the tool assumes some familiarity with systemd, containers, and process trees, so absolute beginners might face a learning curve.

Overall, witr solves a real problem with a pragmatic approach and good engineering discipline. It’s worth exploring if you spend a lot of time debugging running services and want to reduce the manual mental juggling of multiple commands.

→ GitHub Repo: pranshuparmar/witr ⭐ 14,759 · Go