README

witr

 Why is this running?
Trace any process, port, container, or file back to the exact chain that started it —
one command, machine-readable JSON, or an interactive TUI.

   




 🎮 Try witr in your browser →
Investigate a simulated Linux box — a guided tutorial and free-play sandbox, no install required.





---



Purpose • Installation • AI Agents • TUI • Examples

Flags • Output Behavior • Platforms • Sponsors



---

 1. Purpose

witr exists to answer a single question:

 Why is this running?

When something is running on a system, whether it is a process, a service, or something bound to a port, there is always a cause. That cause is often indirect, non-obvious, or spread across multiple layers such as supervisors, containers, services, or shells.

Existing tools (ps, top, lsof, ss, systemctl, docker ps) expose state and metadata. They show _what_ is running, but leave the user to infer _why_ by manually correlating outputs across tools.

witr makes that causality explicit. Ports, services, containers and files all map back to a PID, and for that PID witr answers:

1. What is running?
2. How did it start?
3. What is keeping it running?
4. What context does it belong to?

The answer comes as a single human-readable report, as JSON for scripts and AI agents, or in an interactive TUI dashboard.

bash
witr node                  why is this node process running?
witr --port 8080           what is holding port 8080, and why?
witr --pid 1234 --tree     its ancestry and children as a tree
witr --container redis     a container, across Docker, Podman, Kubernetes and more
witr --port 8080 --json    the same answer for scripts and AI agents
witr                       browse everything in the interactive TUI


 📖 Curious how witr came to be? Read the story.

---

 2. Installation

witr is distributed as a single static binary for Linux, macOS, FreeBSD, and Windows.

witr is also independently packaged and maintained across multiple operating systems and ecosystems. An up-to-date overview of packaging status is available on Repology. Please note that community packages may lag GitHub releases due to independent review and validation.

 [!TIP]
 If you use a package manager (Homebrew, Conda, Winget, etc.), we recommend installing via that for easier updates. Otherwise, the install script is the quickest way to get started.

---

 2.1 Quick Install

 Unix (Linux, macOS & FreeBSD)

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



Script Details

The script will:
- Detect your operating system (linux, darwin or freebsd)
- Detect your CPU architecture (amd64, arm64 or loong64 on Linux)
- Download the latest released binary and man page
- Install it to /usr/local/bin/witr
- Install the man page to /usr/local/share/man/man1/witr.1

To install somewhere else, such as ~/.local (no sudo needed), set INSTALL_PREFIX on bash:

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