witr-process-inspector

Original：🇺🇸 English

Translated

CLI and TUI tool that explains why processes, services, and ports are running by tracing causality chains across supervisors, containers, and shells.

3installs

Sourcearadotso/trending-skills

Added on2026-03-19

NPX Install

npx skill4agent add aradotso/trending-skills witr-process-inspector

SKILL.md Content

View Translation Comparison →

witr — Why Is This Running?

Skill by ara.so — Daily 2026 Skills collection.

witr is a Go CLI/TUI tool that answers "why is this running?" for any process, service, or port. Instead of leaving you to correlate

ps

lsof

ss

systemctl

, and

docker ps

manually, witr makes the causality chain explicit — showing where a running thing came from, how it was started, and what chain of supervisors/containers/shells is responsible.

Installation

Quickest (Unix)

bash

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

Quickest (Windows PowerShell)

powershell

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

Package Managers

bash

# Homebrew (macOS/Linux)
brew install witr

# Conda
conda install -c conda-forge witr

# Arch Linux (AUR)
yay -S witr-bin

# Windows winget
winget install -e --id PranshuParmar.witr

# Windows Scoop
scoop install main/witr

# Alpine / apk
sudo apk add --allow-untrusted ./witr-*.apk

# Go source install
go install github.com/pranshuparmar/witr/cmd/witr@latest

Key Commands & Flags

Basic Usage

bash

# Inspect a process by PID
witr <pid>

# Inspect by process name (substring match)
witr <name>

# Inspect what's bound to a port
witr --port <port>
witr -p <port>

# Launch interactive TUI dashboard
witr --interactive
witr -i

# Show all running processes with causality info
witr --all
witr -a

# Output as JSON (for scripting)
witr --json <pid>

# Follow/watch mode — refresh automatically
witr --watch <pid>
witr -w <pid>

# Verbose output — show full environment and metadata
witr --verbose <pid>
witr -v <pid>

# Filter processes by user
witr --user <username>

# Show version
witr --version

Common Flag Reference

Flag	Short	Description
`--port`	`-p`	Inspect by port number
`--interactive`	`-i`	Launch TUI dashboard
`--all`	`-a`	Show all processes
`--json`		Output as JSON
`--watch`	`-w`	Auto-refresh/follow
`--verbose`	`-v`	Full metadata output
`--user`		Filter by OS user
`--version`		Print version

Interactive TUI Mode

Launch the full dashboard:

bash

witr -i
# or
witr --interactive

TUI Keybindings:

Key	Action
`↑` / `↓`	Navigate process list
`Enter`	Expand process detail / causality chain
`f`	Filter/search processes
`s`	Sort by column
`r`	Refresh
`j`	Toggle JSON view
`q` / `Ctrl+C`	Quit

Example Outputs

Inspect a PID

bash

witr 1234

PID: 1234
Name: node
Binary: /usr/local/bin/node
Started: 2026-03-18 09:12:44
User: ubuntu

Why is this running?
  └─ Started by: npm (PID 1200)
       └─ Started by: bash (PID 1180)
            └─ Started by: sshd (PID 980)
                 └─ Started by: systemd (PID 1) [service: sshd.service]

Inspect by Port

bash

witr --port 8080

Port: 8080 (TCP, LISTEN)
Process: python3 (PID 4512)
Binary: /usr/bin/python3
User: deploy

Why is this running?
  └─ Started by: gunicorn (PID 4490)
       └─ Started by: systemd (PID 1) [service: myapp.service]
            Unit file: /etc/systemd/system/myapp.service
            ExecStart: /usr/bin/gunicorn app:app --bind 0.0.0.0:8080

JSON Output (for scripting)

bash

witr --json 4512

json

{
  "pid": 4512,
  "name": "python3",
  "binary": "/usr/bin/python3",
  "user": "deploy",
  "started_at": "2026-03-18T09:00:00Z",
  "causality_chain": [
    {"pid": 4490, "name": "gunicorn", "type": "parent"},
    {"pid": 1,    "name": "systemd",  "type": "supervisor", "service": "myapp.service"}
  ]
}

Watch/Follow a Process

bash

# Refresh every 2 seconds
witr --watch 4512

Common Patterns

Find Who Started a Port Listener

bash

# Quick check: who owns port 5432 (Postgres)?
witr --port 5432

# Get machine-readable output for automation
witr --json --port 5432 | jq '.causality_chain[-1].service'

Audit All Running Services

bash

# List everything with causality, pipe to less
witr --all | less

# Export full audit to JSON
witr --all --json > audit.json

Inspect a Docker/Container Process

bash

# witr understands container boundaries
witr <pid-of-containerized-process>
# Output will show: container → container runtime → systemd chain

Use in a Shell Script

bash

#!/usr/bin/env bash
# Check if port 8080 is in use and why
if witr --json --port 8080 > /tmp/witr_out.json 2>/dev/null; then
  SERVICE=$(jq -r '.causality_chain[-1].service // "unknown"' /tmp/witr_out.json)
  echo "Port 8080 is owned by service: $SERVICE"
else
  echo "Port 8080 is not in use"
fi

Filter Processes by User

bash

# Show only processes owned by www-data and why they're running
witr --all --user www-data

Platform Support

Platform	Architectures	Notes
Linux	amd64, arm64	Full support
macOS	amd64, arm64 (Apple Silicon)	Full support
Windows	amd64	Full support
FreeBSD	amd64, arm64	Full support

Go Integration (Embedding witr Logic)

If you want to use witr programmatically in a Go project:

bash

go get github.com/pranshuparmar/witr

package main

import (
    "fmt"
    "github.com/pranshuparmar/witr/pkg/inspector"
)

func main() {
    // Inspect a process by PID
    result, err := inspector.InspectPID(1234)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Process: %s\n", result.Name)
    for _, link := range result.CausalityChain {
        fmt.Printf("  └─ %s (PID %d)\n", link.Name, link.PID)
    }
}

// Inspect by port
result, err := inspector.InspectPort(8080, "tcp")
if err != nil {
    panic(err)
}
fmt.Printf("Port 8080 owned by PID %d (%s)\n", result.PID, result.Name)

Troubleshooting

Permission Denied on Some PIDs

bash

# witr needs read access to /proc (Linux) or equivalent
# Run with sudo for system-level processes
sudo witr <pid>
sudo witr --port 80

Binary Not Found After Install

bash

# Ensure install location is in PATH
export PATH="$PATH:/usr/local/bin"   # Unix default install
# or for Go installs:
export PATH="$PATH:$(go env GOPATH)/bin"

Port Not Found / No Output

bash

# Confirm port is actually listening first
ss -tlnp | grep <port>       # Linux
netstat -an | grep <port>    # macOS/Windows

# Then retry
witr --port <port>

TUI Not Rendering Correctly

bash

# Ensure terminal supports 256 colors
export TERM=xterm-256color
witr --interactive

# If on Windows, use Windows Terminal for best TUI experience

Process Exited Before Inspection

bash

# witr can only inspect currently running processes
# Use --watch on a long-running process to monitor it
witr --watch <pid>

macOS: Requires Elevated Access for Some Processes

bash

# System Integrity Protection may restrict some process metadata
sudo witr <pid>

Quick Reference Card

witr <pid>              # Why is PID X running?
witr <name>            # Why is process "nginx" running?
witr -p <port>         # What's on port 8080 and why?
witr -i                # Interactive TUI dashboard
witr -a                # Show all processes + causality
witr --json <pid>      # Machine-readable output
witr -w <pid>          # Watch/follow a process
witr -v <pid>          # Verbose: full env + metadata
witr --user <user>     # Filter by OS user

witr-process-inspector

NPX Install

Tags

SKILL.md Content

witr — Why Is This Running?

Installation

Quickest (Unix)

Quickest (Windows PowerShell)

Package Managers

Key Commands & Flags

Basic Usage

Common Flag Reference

Interactive TUI Mode

Example Outputs

Inspect a PID

Inspect by Port

JSON Output (for scripting)

Watch/Follow a Process

Common Patterns

Find Who Started a Port Listener

Audit All Running Services

Inspect a Docker/Container Process

Use in a Shell Script

Filter Processes by User

Platform Support

Go Integration (Embedding witr Logic)

Troubleshooting

Permission Denied on Some PIDs

Binary Not Found After Install

Port Not Found / No Output

TUI Not Rendering Correctly

Process Exited Before Inspection

macOS: Requires Elevated Access for Some Processes

Quick Reference Card