pranshuparmar/witr

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/pranshuparmar/witr.svg?style=card)](https://bestofgithub.dev/repo/pranshuparmar/witr)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/pranshuparmar/witr.svg)](https://bestofgithub.dev/repo/pranshuparmar/witr)

Loading README…

Code	Meaning
0	Clean: process found, no warnings
1	Warnings: process found but has one or more warnings
2	Not found: no matching process or service (also a port no process on this system holds, when witr runs as root or on Windows)
3	Permission denied: insufficient privileges (retry with sudo)
4	Invalid input: bad arguments or ambiguous match
5	Internal error: an unexpected failure occurred
6	Cause unknown: process found, but what started it can't be traced (its warnings say why). Not used on Windows, where this is routine

Command	Output
`witr <target> --json`	The full report: `Target`, `Process`, `Ancestry`, `Source`, `Warnings` and the rest
`--short --json`	A list of `{PID, Command}` from the top of the chain to the process, with `PPID` and `ParentExited` where the process that started it has exited
`--tree --json`	`{Ancestry, Children}`, each a list of the same entries
`--warnings --json`	`{PID, Process, Command, Warnings}`
`--env --json`	`{PID, Process, Command, Env}`
A container whose processes aren't visible	`{Target, Runtime, ContainerID, ContainerName, Image, …, Note}`
A failed lookup	`{Target, Error}`, plus `Matches` when the target was ambiguous
Several targets	A list of the above, one entry per target, in the order given

Feature	Linux	macOS	Windows	FreeBSD	Notes
Process Selection
By Name	✅	✅	✅	✅
By PID	✅	✅	✅	✅
By Port	✅	✅	✅	✅
By File	✅	✅	✅	✅
By Container	✅	✅	✅	✅	Requires the runtime CLI on PATH (docker/podman/nerdctl/crictl/incus/lxc/lxc-ls/jls).
Multiple/mixed inputs	✅	✅	✅	✅	Repeatable flags, mixed types.
Exact Match	✅	✅	✅	✅
Full command line	✅	✅	✅	✅
Process start time	✅	✅	✅	✅
Working directory	✅	✅	✅	✅
Environment variables	✅	⚠️	⚠️	✅	macOS: SIP restrictions; Windows: protected processes inaccessible.
Network
Listening ports	✅	✅	✅	✅
Connections (remote end)	✅	✅	✅	✅	Connections show their remote end; connections a listener accepted are counted on its row.
Bind addresses	✅	✅	✅	✅
Port → PID resolution	✅	✅	✅	✅
Port → Container fallback	✅	✅	✅	✅	A port held by PID 1 (socket activation), a port forwarder (`docker-proxy`, Docker Desktop, `rootlessport`, `pasta`, RootlessKit) or no process at all is traced to the service or container behind it, in the CLI and the TUI's Ports tab.
Service Detection
Service Manager	✅	✅	✅	✅	Linux: systemd, macOS: launchd, Windows: Services, FreeBSD: rc.d
Service Description	✅	✅	✅	✅	Linux: `Description`, macOS: `Comment`, Windows: `Display Name`, FreeBSD: `rc` header
Configuration Source	✅	✅	✅	✅	Linux: Unit File, macOS: Plist, Windows: Registry Key, FreeBSD: Rc Script
Supervisor	✅	✅	✅	✅
Containers	✅	✅	✅	✅	Docker (plus compose mappings), Podman, nerdctl, K8s (Kubepods/crictl), Containerd. Colima on macOS/Linux. Incus/LXC/LXD on Linux. Jails on FreeBSD.
SSH session detection	✅	✅	✅	✅	Detects remote IP and terminal.
tmux/screen detection	✅	✅	❌	✅	Shows session name in source.
Schedule detection	✅	✅	❌	❌	Linux: systemd timers, macOS: launchd intervals/calendar.
Restart count	✅	⚠️	⚠️	❌	systemd restarts on Linux; container restart count and policy wherever Docker, Podman, nerdctl or Kubernetes runs.
Exited parent detection	✅	✅	⚠️	✅	Marks where the process that started it exited. Windows shows the break but doesn't treat it as a finding (no exit code 6): its launchers routinely exit.
Snap/Flatpak detection	✅	❌	❌	❌
Health & Diagnostics
CPU usage detection	✅	✅	✅	✅
Memory usage detection	✅	✅	✅	✅
Health status detection	✅	✅	✅	✅
Open Files / Handles	✅	✅	⚠️	✅	Windows: count only.
File Locks	✅	✅	❌	✅	Linux: `/proc/locks`; macOS/FreeBSD: derived from `lsof`/`fstat`.
Deleted binary detection	✅	✅	✅	✅	Warns if executable is missing.
Capability warnings	✅	❌	❌	❌	Warns about dangerous capabilities on non-root processes.
Security context	✅	❌	✅	❌	Linux: AppArmor profile or SELinux context; Windows: integrity level (elevated, system, low).
Context
Git repo/branch detection	✅	✅	✅	✅
Interactive Mode (TUI)
Processes Tab	✅	✅	✅	✅
Ports Tab	✅	✅	✅	✅
Containers Tab	✅	✅	✅	✅
Locks Tab	✅	✅	❌	✅	Toggle (`a`) shows all open files.
Process Details	✅	✅	✅	✅
Process Actions	✅	✅	❌	✅

witr

Why is this running?

🎮 Try witr in your browser →

1. Purpose

2. Installation

2.1 Quick Install

Unix (Linux, macOS & FreeBSD)

Windows (PowerShell)

2.2 Package Managers

2.3 Source & Manual Installation

2.4 Run Without Installation

2.5 Other Operations

3. Using witr with AI Coding Agents

Official agent skill

4. Interactive Mode (TUI)

Key Features:

5. Example Outputs

5.1 Name Based Query

5.2 Short Output

5.3 Tree Output

5.4 Multiple Matches

5.5 File Based Query

5.6 Container Based Query

5.7 Multiple Inputs

5.8 Warnings, Verbose and JSON

6. Flags & Options

7. Output Behavior

7.1 Exit Codes

Example Usage:

7.2 Standard Output Sections

Target

Process

Why It Exists

Source

Context (best effort)

Warnings

7.3 JSON Output

8. Platform Support

8.1 Feature Compatibility Matrix

8.2 Permissions Note

Linux/FreeBSD

macOS

Windows

9. Sponsors