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.

It explains where a running thing came from, how it was started, and what chain of systems is responsible for it existing right now, in a single, human-readable output.

• Explain why a process exists, not just that it exists
• Reduce time‑to‑understanding during debugging and outages
• Work with zero configuration
• Be safe, read‑only, and non‑destructive
• Prefer clarity over completeness

• Not a monitoring tool
• Not a performance profiler
• Not a replacement for systemd/docker tooling
• Not a remediation or auto‑fix tool

witr treats everything as a process question.

Ports, services, containers, and commands all eventually map to PIDs. Once a PID is identified, witr builds a causal chain explaining why that PID exists.

At its core, witr answers:

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

witr supports multiple entry points that converge to PID analysis.

witr node
witr nginx

A single positional argument (without flags) is treated as a process or service name. If multiple matches are found, witr will prompt for disambiguation by PID.

witr --pid 14233

Explains why a specific process exists.

witr --port 5000

Explains the process(es) listening on a port.

• Single screen by default (best effort)
• Deterministic ordering
• Narrative-style explanation
• Best-effort detection with explicit uncertainty

What the user asked about.

Executable, PID, user, command, start time and restart count.

A causal ancestry chain showing how the process came to exist. This is the core value of witr.

The primary system responsible for starting or supervising the process (best effort).

Examples:

• systemd unit
• docker container
• pm2
• cron
• interactive shell

Only one primary source is selected.

• Working directory
• Git repository name and branch
• Docker container name / image
• Public vs private bind

Non‑blocking observations such as:

• Process is running as root
• Process is listening on a public interface (0.0.0.0 / ::)
• Restarted multiple times (warning only if above threshold)
• Process is using high memory (>1GB RSS)
• Process has been running for over 90 days

--pid <n>         Explain a specific PID
--port <n>        Explain port usage
--short           One-line summary
--tree            Show full process ancestry tree
--json            Output result as JSON
--warnings        Show only warnings
--no-color        Disable colorized output
--env             Show only environment variables for the process
--help            Show this help message

A single positional argument (without flags) is treated as a process or service name.

witr node

Target      : node

Process     : node (pid 14233)
User        : pm2
Command     : node index.js
Started     : 2 days ago (Mon 2025-02-02 11:42:10 +05:30)
Restarts    : 1

Why It Exists :
  systemd (pid 1) → pm2 (pid 5034) → node (pid 14233)

Source      : pm2

Working Dir : /opt/apps/expense-manager
Git Repo    : expense-manager (main)
Listening   : 127.0.0.1:5001

witr --port 5000 --short

systemd (pid 1) → PM2 v5.3.1: God (pid 1481580) → python (pid 1482060)

witr --pid 1482060 --tree

systemd (pid 1)
  └─ PM2 v5.3.1: God (pid 1481580)
    └─ python (pid 1482060)

witr node

Multiple matching processes found:

[1] PID 12091  node server.js  (docker)
[2] PID 14233  node index.js   (pm2)
[3] PID 18801  node worker.js  (manual)

Re-run with:
  witr --pid <pid>

witr nginx

Ambiguous target: "nginx"

The name matches multiple entities:

[1] PID 2311   nginx: master process   (service)
[2] PID 24891  nginx: worker process   (manual)

witr cannot determine intent safely.
Please re-run with an explicit PID:
  witr --pid <pid>

witr is distributed as a single static Linux binary.

The easiest way to install witr is via the install script.

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

curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh -o install.sh
cat install.sh
chmod +x install.sh
./install.sh

The script will:

• Detect your CPU architecture (amd64 or arm64)
• 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

You may be prompted for your password to write to system directories.

If you prefer manual installation, follow these simple steps for your architecture:

# Download the binary
curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr-linux-amd64 -o witr-linux-amd64

# Verify checksum (Optional, should print OK)
curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS -o SHA256SUMS
grep witr-linux-amd64 SHA256SUMS | sha256sum -c -

# Rename and install
mv witr-linux-amd64 witr && chmod +x witr
sudo mv witr /usr/local/bin/witr

# Install the man page (Optional)
sudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1
sudo mandb >/dev/null 2>&1 || true

# Download the binary
curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr-linux-arm64 -o witr-linux-arm64

# Verify checksum (Optional, should print OK)
curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS -o SHA256SUMS
grep witr-linux-arm64 SHA256SUMS | sha256sum -c -

# Rename and install
mv witr-linux-arm64 witr && chmod +x witr
sudo mv witr /usr/local/bin/witr

# Install the man page (Optional)
sudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1
sudo mandb >/dev/null 2>&1 || true

Explanation:

• Download only the binary for your architecture and the SHA256SUMS file.
• Verify the checksum for your binary only (prints OK if valid).
• Rename to witr, make it executable, and move to your PATH.
• Install man page.

witr --version
man witr

To completely remove witr:

sudo rm -f /usr/local/bin/witr
sudo rm -f /usr/local/share/man/man1/witr.1

• Linux

witr inspects /proc and may require elevated permissions to explain certain processes.

If you are not seeing the expected information (e.g., missing process ancestry, user, working directory or environment details), try running witr with sudo for elevated permissions:

sudo witr [your arguments]

witr is successful if:

• An engineer can answer "why is this running?" within seconds
• It reduces reliance on multiple tools
• Output is understandable under stress
• Users trust it during incidents

This project was developed with assistance from AI/LLMs (including GitHub Copilot, ChatGPT, and related tools), supervised by a human who occasionally knew what he was doing.