PaperclipOrg
Claude Agent Skill · by Aradotso

Witr Process Inspector

Install Witr Process Inspector skill for Claude Code from aradotso/trending-skills.

Install
Terminal · npx
$npx skills add https://github.com/obra/superpowers --skill test-driven-development
Works with Paperclip

How Witr Process Inspector fits into a Paperclip company.

Witr Process Inspector drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md363 lines
Expand
---name: witr-process-inspectordescription: CLI and TUI tool that explains why processes, services, and ports are running by tracing causality chains across supervisors, containers, and shells.triggers:  - "why is this process running"  - "inspect running processes with witr"  - "trace process causality"  - "find what started a service"  - "witr TUI dashboard"  - "check what's listening on a port"  - "use witr to debug running services"  - "explain process chain with witr"--- # witr — Why Is This Running? > Skill by [ara.so](https://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)```bashcurl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash``` ### Quickest (Windows PowerShell)```powershellirm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex``` ### Package Managers```bash# Homebrew (macOS/Linux)brew install witr # Condaconda install -c conda-forge witr # Arch Linux (AUR)yay -S witr-bin # Windows wingetwinget install -e --id PranshuParmar.witr # Windows Scoopscoop install main/witr # Alpine / apksudo apk add --allow-untrusted ./witr-*.apk # Go source installgo install github.com/pranshuparmar/witr/cmd/witr@latest``` --- ## Key Commands & Flags ### Basic Usage```bash# Inspect a process by PIDwitr <pid> # Inspect by process name (substring match)witr <name> # Inspect what's bound to a portwitr --port <port>witr -p <port> # Launch interactive TUI dashboardwitr --interactivewitr -i # Show all running processes with causality infowitr --allwitr -a # Output as JSON (for scripting)witr --json <pid> # Follow/watch mode — refresh automaticallywitr --watch <pid>witr -w <pid> # Verbose output — show full environment and metadatawitr --verbose <pid>witr -v <pid> # Filter processes by userwitr --user <username> # Show versionwitr --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:```bashwitr -i# orwitr --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```bashwitr 1234``````PID: 1234Name: nodeBinary: /usr/local/bin/nodeStarted: 2026-03-18 09:12:44User: 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```bashwitr --port 8080``````Port: 8080 (TCP, LISTEN)Process: python3 (PID 4512)Binary: /usr/bin/python3User: 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)```bashwitr --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 secondswitr --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 automationwitr --json --port 5432 | jq '.causality_chain[-1].service'``` ### Audit All Running Services```bash# List everything with causality, pipe to lesswitr --all | less # Export full audit to JSONwitr --all --json > audit.json``` ### Inspect a Docker/Container Process```bash# witr understands container boundarieswitr <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 whyif 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 runningwitr --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: ```bashgo get github.com/pranshuparmar/witr``` ```gopackage 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)    }}``` ```go// Inspect by portresult, 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 processessudo witr <pid>sudo witr --port 80``` ### Binary Not Found After Install```bash# Ensure install location is in PATHexport 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 firstss -tlnp | grep <port>       # Linuxnetstat -an | grep <port>    # macOS/Windows # Then retrywitr --port <port>``` ### TUI Not Rendering Correctly```bash# Ensure terminal supports 256 colorsexport TERM=xterm-256colorwitr --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 itwitr --watch <pid>``` ### macOS: Requires Elevated Access for Some Processes```bash# System Integrity Protection may restrict some process metadatasudo 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 dashboardwitr -a                # Show all processes + causalitywitr --json <pid>      # Machine-readable outputwitr -w <pid>          # Watch/follow a processwitr -v <pid>          # Verbose: full env + metadatawitr --user <user>     # Filter by OS user```