- 1. Purpose
- 2. Goals
- 3. Core Concept
- 4. Supported Targets
- 5. Output Behavior
- 6. Flags & Options
- 7. Example Outputs
- 8. Installation
- 9. Platform Support
- 10. Success Criteria
- 11. AI Assistance Disclaimer
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:
- What is running?
- How did it start?
- What is keeping it running?
- What context does it belong to?
witr supports multiple entry points that converge to PID analysis.
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.
Explains why a specific process exists.
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.
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
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)
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>
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 | bashcurl -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 (
amd64orarm64) - 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.
To completely remove witr:
sudo rm -f /usr/local/bin/witr sudo rm -f /usr/local/share/man/man1/witr.1
If you use Nix, you can build witr from source and run without installation:
nix run github:pranshuparmar/witr -- --port 5000
- 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:
- A user 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.