Skip to content
Back to search

witr

MarketplaceWorks with Claude CodeGitHub

Why is this running? Trace any process, port, container, or file back to what started it - CLI + TUI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pranshuparmar--witr/badge.svg)](/listings/pranshuparmar--witr)

HTML

<a href="/listings/pranshuparmar--witr"><img src="/api/listings/pranshuparmar--witr/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

witr is distributed as a single static binary for Linux, macOS, FreeBSD, and Windows.

witr is also independently packaged and maintained across multiple operating systems and ecosystems. An up-to-date overview of packaging status is available on [Repology](https://repology.org/project/witr/versions). Please note that community packages may lag GitHub releases due to independent review and validation.

> [!TIP] > If you use a package manager (Homebrew, Conda, Winget, etc.), we recommend installing via that for easier updates. Otherwise, the install script is the quickest way to get started.

---

2.1 Quick Install

Unix (Linux, macOS & FreeBSD)

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

<details> <summary>Script Details</summary>

The script will: - Detect your operating system (`linux`, `darwin` or `freebsd`) - Detect your CPU architecture (`amd64`, `arm64` or `loong64` on Linux) - 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` - Pass INSTALL_PREFIX to override default install path

</details>

Windows (PowerShell)

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

<details> <summary>Script Details</summary>

The script will: - Download the latest release (zip) and verify checksum. - Extract `witr.exe` to `%LocalAppData%\witr\bin`. - Add the bin directory to your User `PATH`.

</details>

---

2.2 Package Managers

<details> <summary><strong>APT (Debian, Ubuntu & Derivatives)</strong> <a href="https://packages.debian.org/sid/witr"><img src="https://repology.org/badge/version-for-repo/debian_unstable/witr.svg?style=flat-square" alt="Debian"></a></summary> <br>

You can install **witr** from the official Debian and Ubuntu repositories (Ubuntu 26.04+, Debian sid and later), as well as derivative distributions like Kali Linux, Devuan, and Raspbian:

sudo apt install witr

> Note: The apt-shipped version may lag the latest GitHub release. For the newest features, use the install script or another installation method. </details>

<details> <summary><strong>Homebrew (macOS & Linux)</strong> <a href="https://formulae.brew.sh/formula/witr"><img src="https://img.shields.io/homebrew/v/witr?style=flat-square" alt="Homebrew"></a></summary> <br>

You can install **witr** using [Homebrew](https://brew.sh/) on macOS or Linux:

brew install witr

</details>

<details> <summary><strong>MacPorts (macOS)</strong> <a href="https://ports.macports.org/port/witr/"><img src="https://repology.org/badge/version-for-repo/macports/witr.svg?style=flat-square" alt="MacPorts"></a></summary> <br>

You can install **witr** using [MacPorts](https://www.macports.org/) on macOS:

sudo port install witr

</details>

<details> <summary><strong>Conda (macOS, Linux & Windows)</strong> <a href="https://anaconda.org/conda-forge/witr"><img src="https://img.shields.io/conda/vn/conda-forge/witr?style=flat-square" alt="Conda"></a></summary> <br>

You can install **witr** using [conda](https://docs.conda.io/en/latest/), [mamba](https://mamba.readthedocs.io/en/latest/), or [pixi](https://pixi.prefix.dev/latest/) on macOS, Linux, and Windows:

conda install -c conda-forge witr
# alternatively using mamba
mamba install -c conda-forge witr
# alternatively using pixi
pixi global install witr

</details>

<details> <summary><strong>Arch Linux (AUR)</strong> <a href="https://aur.archlinux.org/packages/witr-bin"><img src="https://img.shields.io/aur/version/witr-bin?style=flat-square" alt="AUR"></a></summary> <br>

On Arch Linux and derivatives, install from the [AUR package](https://aur.archlinux.org/packages/witr-bin):

yay -S witr-bin
# alternatively using paru
paru -S witr-bin
# or use your preferred AUR helper

</details>

<details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "witr",
  3. "owner": {
  4. "name": "Pranshu Parmar",
  5. "url": "https://github.com/pranshuparmar"
  6. },
  7. "metadata": {
  8. "description": "The official witr plugin: an agent skill for explaining why a process is running and what started it."
  9. },
  10. "plugins": [
  11. {
  12. "name": "witr",
  13. "source": "./plugins/witr",
  14. "description": "Explains why a process is running and what started it: the official skill for using the witr CLI."
  15. }
  16. ]
  17. }
README.md · README · 1,149 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # witr
  3. ### Why is this running?
  4. Trace any process, port, container, or file back to the exact chain that started it —<br>
  5. one command, machine-readable JSON, or an [interactive TUI](#4-interactive-mode-tui).
  6. [![Latest Release](https://img.shields.io/github/v/release/pranshuparmar/witr?label=Latest%20Release&style=flat-square)](https://github.com/pranshuparmar/witr/releases/latest) [![Platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macos%20%7C%20windows%20%7C%20freebsd-blue?style=flat-square)](#8-platform-support) <br> [![Package Managers](https://img.shields.io/badge/Package%20Managers-brew%20|%20conda%20|%20aur%20|%20winget%20|%20npm%20|%20ports%20|%20...%20-blue?style=flat-square)](https://repology.org/project/witr/versions)
  7. <a href="https://trendshift.io/repositories/18714" target="_blank"><img src="https://trendshift.io/api/badge/repositories/18714" alt="pranshuparmar/witr on Trendshift" width="250" height="55" /></a>
  8. <a href="https://www.producthunt.com/products/witr?embed=true&amp;utm_source=badge-featured&amp;utm_medium=badge&amp;utm_campaign=badge-witr" target="_blank" rel="noopener noreferrer"><img alt="witr - Why is this running? Trace process, port, container or file. | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1211309&amp;theme=light&amp;t=1785480480150"></a>
  9. ### 🎮 [**Try witr in your browser →**](https://pranshuparmar.github.io/witr/)
  10. *Investigate a simulated Linux box — a guided tutorial and free-play sandbox, no install required.*
  11. <a href="https://pranshuparmar.github.io/witr/"><img width="1232" alt="witr's interactive TUI and CLI answering why a node process is running — the same systemd → PM2 → node chain in both" src="https://github.com/user-attachments/assets/dbe271ad-25e5-425b-b414-392d0c4eee37" /></a>
  12. </div>
  13. ---
  14. <div align="center">
  15. [**Purpose**](#1-purpose) • [**Installation**](#2-installation) • [**AI Agents**](#3-using-witr-with-ai-coding-agents) • [**TUI**](#4-interactive-mode-tui) • [**Examples**](#5-example-outputs)
  16. <br>
  17. [**Flags**](#6-flags--options) • [**Output Behavior**](#7-output-behavior) • [**Platforms**](#8-platform-support) • [**Sponsors**](#9-sponsors)
  18. </div>
  19. ---
  20. ## 1. Purpose
  21. **witr** exists to answer a single question:
  22. > **Why is this running?**
  23. 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.
  24. 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.
  25. **witr** makes that causality explicit. Ports, services, containers and files all map back to a **PID**, and for that PID witr answers:
  26. 1. What is running?
  27. 2. How did it start?
  28. 3. What is keeping it running?
  29. 4. What context does it belong to?
  30. The answer comes as a single human-readable report, as JSON for scripts and AI agents, or in an **interactive TUI dashboard**.
  31. ```bash
  32. witr node # why is this node process running?
  33. witr --port 8080 # what is holding port 8080, and why?
  34. witr --pid 1234 --tree # its ancestry and children as a tree
  35. witr --container redis # a container, across Docker, Podman, Kubernetes and more
  36. witr --port 8080 --json # the same answer for scripts and AI agents
  37. witr # browse everything in the interactive TUI
  38. ```
  39. > 📖 Curious how witr came to be? [Read the story](https://medium.com/@pranshu.parmar/witr-why-is-this-running-a9a97cbedd18).
  40. ---
  41. ## 2. Installation
  42. witr is distributed as a single static binary for Linux, macOS, FreeBSD, and Windows.
  43. witr is also independently packaged and maintained across multiple operating systems and ecosystems. An up-to-date overview of packaging status is available on [Repology](https://repology.org/project/witr/versions). Please note that community packages may lag GitHub releases due to independent review and validation.
  44. > [!TIP]
  45. > If you use a package manager (Homebrew, Conda, Winget, etc.), we recommend installing via that for easier updates. Otherwise, the install script is the quickest way to get started.
  46. ---
  47. ### 2.1 Quick Install
  48. #### Unix (Linux, macOS & FreeBSD)
  49. ```bash
  50. curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash
  51. ```
  52. <details>
  53. <summary>Script Details</summary>
  54. The script will:
  55. - Detect your operating system (`linux`, `darwin` or `freebsd`)
  56. - Detect your CPU architecture (`amd64`, `arm64` or `loong64` on Linux)
  57. - Download the latest released binary and man page
  58. - Install it to `/usr/local/bin/witr`
  59. - Install the man page to `/usr/local/share/man/man1/witr.1`
  60. To install somewhere else, such as `~/.local` (no sudo needed), set `INSTALL_PREFIX` on `bash`:
  61. ```bash
  62. curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | INSTALL_PREFIX="$HOME/.local" bash
  63. ```
  64. </details>
  65. #### Windows (PowerShell)
  66. ```powershell
  67. irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex
  68. ```
  69. <details>
  70. <summary>Script Details</summary>
  71. The script will:
  72. - Download the latest release (zip) and verify checksum.
  73. - Extract `witr.exe` to `%LocalAppData%\witr\bin`.
  74. - Add the bin directory to your User `PATH`.
  75. </details>
  76. ---
  77. ### 2.2 Package Managers
  78. <details>
  79. <summary><strong>APT (Debian, Ubuntu & Derivatives)</strong> <a href="https://packages.debian.org/sid/witr"><img src="https://repology.org/badge/version-for-repo/debian_unstable/witr.svg?style=flat-square" alt="Debian"></a></summary>
  80. <br>
  81. You can install **witr** from the official Debian and Ubuntu repositories (Ubuntu 26.04+, Debian sid and later), as well as derivative distributions like Kali Linux, Devuan, and Raspbian:
  82. ```bash
  83. sudo apt install witr
  84. ```
  85. > Note: The apt-shipped version may lag the latest GitHub release. For the newest features, use the install script or another installation method.
  86. </details>
  87. <details>
  88. <summary><strong>Homebrew (macOS & Linux)</strong> <a href="https://formulae.brew.sh/formula/witr"><img src="https://img.shields.io/homebrew/v/witr?style=flat-square" alt="Homebrew"></a></summary>
  89. <br>
  90. You can install **witr** using [Homebrew](https://brew.sh/) on macOS or Linux:
  91. ```bash
  92. brew install witr
  93. ```
  94. </details>
  95. <details>
  96. <summary><strong>MacPorts (macOS)</strong> <a href="https://ports.macports.org/port/witr/"><img src="https://repology.org/badge/version-for-repo/macports/witr.svg?style=flat-square" alt="MacPorts"></a></summary>
  97. <br>
  98. You can install **witr** using [MacPorts](https://www.macports.org/) on macOS:
  99. ```bash
  100. sudo port install witr
  101. ```
  102. </details>
  103. <details>
  104. <summary><strong>Conda (macOS, Linux & Windows)</strong> <a href="https://anaconda.org/conda-forge/witr"><img src="https://img.shields.io/conda/vn/conda-forge/witr?style=flat-square" alt="Conda"></a></summary>
  105. <br>
  106. You can install **witr** using [conda](https://docs.conda.io/en/latest/), [mamba](https://mamba.readthedocs.io/en/latest/), or [pixi](https://pixi.prefix.dev/latest/) on macOS, Linux, and Windows:
  107. ```bash
  108. conda install -c conda-forge witr
  109. # alternatively using mamba
  110. mamba install -c conda-forge witr
  111. # alternatively using pixi
  112. pixi global install witr
  113. ```
  114. </details>
  115. <details>
  116. <summary><strong>Arch Linux (AUR)</strong> <a href="https://aur.archlinux.org/packages/witr-bin"><img src="https://img.shields.io/aur/version/witr-bin?style=flat-square" alt="AUR"></a></summary>
  117. <br>
  118. On Arch Linux and derivatives, install from the [AUR package](https://aur.archlinux.org/packages/witr-bin):
  119. ```bash
  120. yay -S witr-bin
  121. # alternatively using paru
  122. paru -S witr-bin
  123. # or use your preferred AUR helper
  124. ```
  125. </details>
  126. <details>
  127. <summary><strong>Winget (Windows)</strong> <a href="https://winstall.app/apps/PranshuParmar.witr"><img src="https://img.shields.io/winget/v/PranshuParmar.witr?style=flat-square" alt="Winget"></a></summary>
  128. <br>
  129. You can install **witr** via [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/):
  130. ```powershell
  131. winget install -e --id PranshuParmar.witr
  132. ```
  133. </details>
  134. <details>
  135. <summary><strong>NPM (Cross-platform)</strong> <a href="https://www.npmjs.com/package/@pranshuparmar/witr"><img src="https://img.shields.io/npm/v/@pranshuparmar/witr?label=npm&color=blue&style=flat-square" alt="NPM"></a></summary>
  136. <br>
  137. You can install **witr** using [npm](https://www.npmjs.com/package/@pranshuparmar/witr):
  138. ```bash
  139. npm install -g @pranshuparmar/witr
  140. ```
  141. </details>
  142. <details>
  143. <summary><strong>FreeBSD Ports</strong> <a href="https://www.freshports.org/sysutils/witr/"><img src="https://repology.org/badge/version-for-repo/freebsd/witr.svg?style=flat-square" alt="FreeBSD Port"></a></summary>
  144. <br>
  145. You can install **witr** on FreeBSD from the [FreshPorts port](https://www.freshports.org/sysutils/witr/):
  146. ```bash
  147. pkg install witr
  148. # or
  149. pkg install sysutils/witr
  150. ```
  151. Or build from Ports:
  152. ```bash
  153. cd /usr/ports/sysutils/witr/
  154. make install clean
  155. ```
  156. </details>
  157. <details>
  158. <summary><strong>Chocolatey (Windows)</strong> <a href="https://community.chocolatey.org/packages/witr"><img src="https://img.shields.io/chocolatey/v/witr?style=flat-square" alt="Chocolatey"></a></summary>
  159. <br>
  160. You can install **witr** using [Chocolatey](https://community.chocolatey.org):
  161. ```powershell
  162. choco install witr
  163. ```
  164. </details>
  165. <details>
  166. <summary><strong>Scoop (Windows)</strong> <a href="https://scoop.sh/#/apps?q=witr"><img src="https://img.shields.io/scoop/v/witr?bucket=main&style=flat-square" alt="Scoop"></a></summary>
  167. <br>
  168. You can install **witr** using [Scoop](https://scoop.sh):
  169. ```powershell
  170. scoop install main/witr
  171. ```
  172. </details>
  173. <details>
  174. <summary><strong>AOSC OS</strong> <a href="https://packages.aosc.io/packages/witr"><img src="https://repology.org/badge/version-for-repo/aosc/witr.svg?style=flat-square" alt="AOSC OS"></a></summary>
  175. <br>
  176. You can install **witr** from the [AOSC OS repository](https://packages.aosc.io/packages/witr):
  177. ```bash
  178. oma install witr
  179. ```
  180. </details>
  181. <details>
  182. <summary><strong>GNU Guix</strong> <a href="https://packages.guix.gnu.org/packages/witr/"><img src="https://repology.org/badge/version-for-repo/gnuguix/witr.svg?style=flat-square" alt="GNU Guix"></a></summary>
  183. <br>
  184. You can install **witr** from the [GNU Guix repository](https://packages.guix.gnu.org/packages/witr/):
  185. ```bash
  186. guix install witr
  187. ```
  188. </details>
  189. <details>
  190. <summary><strong>Uniget (Linux)</strong> <a href="https://github.com/uniget-org/tools/tree/main/tools/witr"><img src="https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Funiget-org%2Ftools%2Fmain%2Ftools%2Fwitr%2Fmanifest.yaml&query=%24.version&label=uniget&style=flat-square&color=blue" alt="Uniget"></a></summary>
  191. <br>
  192. You can install **witr** using [uniget](https://uniget.dev/):
  193. ```bash
  194. uniget install witr
  195. ```
  196. </details>
  197. <details>
  198. <summary><strong>Aqua (macOS, Linux & Windows)</strong> <a href="https://github.com/aquaproj/aqua-registry/blob/main/pkgs/pranshuparmar/witr"><img src="https://img.shields.io/badge/dynamic/yaml?url=https%3A%2F%2Fraw.githubusercontent.com%2Faquaproj%2Faqua-registry%2Fmain%2Fpkgs%2Fpranshuparmar%2Fwitr%2Fpkg.yaml&query=%24.packages%5B0%5D.name&label=aqua&style=flat-square&color=blue" alt="Aqua"></a></summary>
  199. <br>
  200. You can install **witr** using [aqua](https://aquaproj.github.io/):
  201. ```bash
  202. # Add package
  203. aqua g -i pranshuparmar/witr
  204. # Install package
  205. aqua i pranshuparmar/witr
  206. ```
  207. </details>
  208. <details>
  209. <summary><strong>Brioche (Linux)</strong> <a href="https://github.com/brioche-dev/brioche-packages/tree/main/packages/witr"><img src="https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbrioche-dev%2Fbrioche-packages%2Fmain%2Fpackages%2Fwitr%2Fproject.bri&search=version%3A%20%22(%5B%5E%22%5D%2B)%22&replace=v%241&label=brioche&color=blue&style=flat-square" alt="Brioche"></a></summary>
  210. <br>
  211. You can install **witr** using [brioche](https://brioche.dev/):
  212. ```bash
  213. brioche install -r witr
  214. ```
  215. </details>
  216. <details>
  217. <summary><strong>Mise (macOS, Linux & Windows)</strong> <a href="https://github.com/pranshuparmar/witr/releases/latest"><img src="https://img.shields.io/github/v/release/pranshuparmar/witr?label=mise&style=flat-square" alt="Mise"></a></summary>
  218. <br>
  219. You can install **witr** using [mise](https://mise.jdx.dev/):
  220. ```bash
  221. mise use github:pranshuparmar/witr
  222. ```
  223. </details>
  224. <details>
  225. <summary><strong>Prebuilt Packages (deb, rpm, apk)</strong></summary>
  226. <br>
  227. **witr** provides native packages for major Linux distributions. You can download the latest `.deb`, `.rpm`, or `.apk` package from the [GitHub releases page](https://github.com/pranshuparmar/witr/releases/latest).
  228. - Generic download command using `curl`:
  229. ```bash
  230. # Replace <package name with the actual package that you need>
  231. curl -LO https://github.com/pranshuparmar/witr/releases/latest/download/<package-name>
  232. ```
  233. - **Debian/Ubuntu (.deb):**
  234. ```bash
  235. sudo dpkg -i ./witr-*.deb
  236. # Or, using apt for dependency resolution:
  237. sudo apt install ./witr-*.deb
  238. ```
  239. - **Fedora/RHEL/CentOS (.rpm):**
  240. ```bash
  241. sudo rpm -i ./witr-*.rpm
  242. ```
  243. - **Alpine Linux (.apk):**
  244. ```bash
  245. sudo apk add --allow-untrusted ./witr-*.apk
  246. ```
  247. </details>
  248. ---
  249. ### 2.3 Source & Manual Installation
  250. <details>
  251. <summary><strong>Go (cross-platform)</strong></summary>
  252. <br>
  253. You can install the latest version directly from source:
  254. ```bash
  255. go install github.com/pranshuparmar/witr/cmd/witr@latest
  256. ```
  257. This will place the `witr` binary in your `$GOPATH/bin` or `$HOME/go/bin` directory. Make sure this directory is in your `PATH`.
  258. </details>
  259. <details>
  260. <summary><strong>Manual Installation</strong></summary>
  261. <br>
  262. If you prefer manual installation, follow these simple steps for your platform:
  263. **Unix (Linux, macOS, FreeBSD)**
  264. ```bash
  265. # 1. Determine OS and Architecture
  266. OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  267. ARCH=$(uname -m)
  268. [ "$ARCH" = "x86_64" ] && ARCH="amd64"
  269. [ "$ARCH" = "aarch64" ] && ARCH="arm64"
  270. [ "$ARCH" = "loongarch64" ] && ARCH="loong64"
  271. # 2. Download the binary
  272. curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/witr-${OS}-${ARCH}" -o witr
  273. # 3. Verify checksum (Optional)
  274. curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -o SHA256SUMS
  275. grep "witr-${OS}-${ARCH}" SHA256SUMS | (sha256sum -c - 2>/dev/null || shasum -a 256 -c - 2>/dev/null)
  276. rm SHA256SUMS
  277. # 4. Rename and install
  278. chmod +x witr
  279. sudo mkdir -p /usr/local/bin
  280. sudo mv witr /usr/local/bin/witr
  281. # 5. Install man page (Optional)
  282. sudo mkdir -p /usr/local/share/man/man1
  283. sudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1
  284. ```
  285. **Windows (PowerShell)**
  286. ```powershell
  287. # 1. Determine Architecture
  288. if ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") {
  289. $ZipName = "witr-windows-amd64.zip"
  290. } elseif ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") {
  291. $ZipName = "witr-windows-arm64.zip"
  292. } else {
  293. throw "Unsupported architecture: $($env:PROCESSOR_ARCHITECTURE)"
  294. }
  295. # 2. Download the zip
  296. Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName" -OutFile "witr.zip"
  297. # 3. Extract the binary
  298. Expand-Archive -Path "witr.zip" -DestinationPath "." -Force
  299. # 4. Verify checksum (Optional)
  300. Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -OutFile "SHA256SUMS"
  301. $hash = Get-FileHash -Algorithm SHA256 .\witr.zip
  302. $expected = Select-String -Path .\SHA256SUMS -Pattern $ZipName
  303. if ($expected -and $hash.Hash.ToLower() -eq $expected.Line.Split(' ')[0]) { Write-Host "Checksum OK" } else { Write-Host "Checksum Mismatch" }
  304. # 5. Install to local bin directory
  305. $InstallDir = "$env:LocalAppData\witr\bin"
  306. New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
  307. Move-Item .\witr.exe $InstallDir\witr.exe -Force
  308. # 6. Add to User Path (Persistent)
  309. $UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
  310. if ($UserPath -notlike "*$InstallDir*") {
  311. [Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User")
  312. $env:Path += ";$InstallDir"
  313. Write-Host "Added to Path. You may need to restart PowerShell."
  314. }
  315. # 7. Cleanup
  316. Remove-Item witr.zip
  317. Remove-Item SHA256SUMS
  318. ```
  319. </details>
  320. ---
  321. ### 2.4 Run Without Installation
  322. <details>
  323. <summary><strong>Nix Flake</strong></summary>
  324. <br>
  325. If you use Nix, you can build **witr** from source and run without installation:
  326. ```bash
  327. nix run github:pranshuparmar/witr -- --help
  328. ```
  329. </details>
  330. <details>
  331. <summary><strong>Pixi</strong></summary>
  332. <br>
  333. If you use [pixi](https://pixi.prefix.dev/latest/), you can run without installation on Linux or macOS:
  334. ```bash
  335. pixi exec witr --help
  336. ```
  337. </details>
  338. ---
  339. ### 2.5 Other Operations
  340. <details>
  341. <summary><strong>Verify Installation</strong></summary>
  342. <br>
  343. ```bash
  344. witr --version
  345. man witr
  346. ```
  347. </details>
  348. <details>
  349. <summary><strong>Shell Completions</strong></summary>
  350. <br>
  351. `witr` supports tab completion for all flags. To enable it, add the appropriate line to your shell configuration:
  352. **Bash**
  353. ```bash
  354. echo 'eval "$(witr completion bash)"' >> ~/.bashrc
  355. source ~/.bashrc
  356. ```
  357. **Zsh**
  358. ```zsh
  359. echo 'eval "$(witr completion zsh)"' >> ~/.zshrc
  360. source ~/.zshrc
  361. ```
  362. **Fish**
  363. ```fish
  364. witr completion fish | source
  365. # To make it permanent:
  366. witr completion fish > ~/.config/fish/completions/witr.fish
  367. ```
  368. **PowerShell**
  369. ```powershell
  370. witr completion powershell | Out-String | Invoke-Expression
  371. # To make it permanent, add the above line to your $PROFILE
  372. ```
  373. </details>
  374. <details>
  375. <summary><strong>Uninstallation</strong></summary>
  376. <br>
  377. If you installed via a package manager (Homebrew, Conda, etc.), please use the respective uninstall command (e.g., `brew uninstall witr`).
  378. To completely remove script/manual installation of **witr**:
  379. **Unix (Linux, macOS, FreeBSD)**
  380. ```bash
  381. sudo rm -f /usr/local/bin/witr
  382. sudo rm -f /usr/local/share/man/man1/witr.1
  383. ```
  384. **Windows**
  385. ```powershell
  386. Remove-Item -Recurse -Force "$env:LocalAppData\witr"
  387. # Remove the install directory from your User PATH
  388. $InstallDir = "$env:LocalAppData\witr\bin"
  389. $UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
  390. [Environment]::SetEnvironmentVariable("Path", (($UserPath -split ';') | Where-Object { $_ -and $_ -ne $InstallDir }) -join ';', "User")
  391. ```
  392. </details>
  393. ---
  394. ## 3. Using witr with AI Coding Agents
  395. AI coding agents (Claude Code, Codex, Cursor and others) regularly run into ports that are already in use, leftover dev servers and confusing containers, and work around them by chaining `lsof`, `ps`, `netstat` and `docker ps`. witr answers the same questions in one command, and two things make it easy for an agent to use:
  396. - **`--json`** prints the full report (the process, its ancestry chain, the source that started it and any warnings), and a failed lookup as `{Target, Error}`. Every shape is listed in [7.3 JSON Output](#73-json-output).
  397. - **Exit codes** say what happened without parsing any text (see [7.1 Exit Codes](#71-exit-codes)). Exit code `1` means the process was found and has warnings; it is not a failure.
  398. Add a short note like this to your project's agent instructions (`AGENTS.md`, `CLAUDE.md` or similar):
  399. ```markdown
  400. ## Process and port debugging
  401. Use `witr` instead of chaining lsof/ps/netstat/docker commands:
  402. - Port already in use: `witr --port <PORT> --json`
  403. - Unknown or stuck process: `witr <name> --json`, or `witr --pid <PID> --tree`
  404. - Container: `witr --container <name or ID> --json`
  405. Exit codes: 0 found, 1 found with warnings (not a failure), 2 not found,
  406. 3 permission denied (retry with sudo), 4 ambiguous name or bad input
  407. (re-run with --pid), 5 internal error, 6 found but what started it can't
  408. be traced. Run `witr --help` for all options.
  409. ```
  410. ### Official agent skill
  411. For fuller guidance, install the official skill: it tells an agent which command fits the situation, how to read the JSON and exit codes, and to ask before stopping anything witr finds. The `witr` binary still needs to be installed.
  412. - **Claude Code:** run `/plugin marketplace add pranshuparmar/witr`, then `/plugin install witr@witr`.
  413. - **Other agents that read Agent Skills, or a manual install:** copy [`plugins/witr/skills/witr`](plugins/witr/skills/witr) into the agent's skills folder (for Claude Code, `~/.claude/skills/`).
  414. ---
  415. ## 4. Interactive Mode (TUI)
  416. Running `witr` without any arguments or with the `-i` flag launches the **Interactive Mode (TUI)**. This provides a real-time, terminal-based dashboard with four tabs for exploring processes, ports, containers, and file locks. Combine `-i` with a target to open the TUI already focused on it: `witr -i -p 1234` selects that PID, `witr -i nginx` pre-fills the process filter, and `witr -i -o 5432` / `-c web` / `-f /path` open the Ports / Containers / Locks tab with the filter set.
  417. ### Key Features:
  418. - **Processes Tab**: Live, sortable, filterable list of all running processes with a side panel showing the ancestry tree of the highlighted process.
  419. - **Ports Tab**: Open/listening ports with the owning processes attached in a side panel. Toggle between LISTEN-only and ALL with `a`. Enter on an owner opens it, or the container a port is published for; an owner hidden from your user shows the user it runs as (run with sudo to see the process).
  420. - **Containers Tab**: All running containers across Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, and FreeBSD jails in one list - name, image, status, ports, command, plus a per-container detail view with mounts, networks, and compose project metadata.
  421. - **Locks Tab**: System-wide file locks (POSIX/FLOCK on Linux, from `lsof` on macOS and `fstat` on FreeBSD). Press `a` to switch into "all open files" mode, where locked entries are merged with every interesting open fd; type into `/` to search across the merged set.
  422. - **Process Details**: Deep-dive into a process to see its full ancestry tree, child processes, environment variables, working directory, sockets, file context, and more.
  423. - **Process Actions**: Send signals (Kill, Terminate, Pause, Resume) or Renice processes directly from the UI (Unix only). Press `a` on a process in the list or in its detail view; the confirmation names the exact process before anything is sent.
  424. - **Mouse Support**: Navigate, sort columns, and click rows using your mouse.
  425. - **Adaptive Theme**: Colors adapt automatically to light and dark terminal backgrounds.
  426. - **Auto-Refresh**: The process, port, container, and lock lists refresh automatically on an adaptive cadence (starts at 3 seconds, backing off under load).
  427. ---
  428. ## 5. Example Outputs
  429. > 💡 Prefer learning by doing? These examples come from the simulated box in the [interactive browser tutorial](https://pranshuparmar.github.io/witr/), where you can run them yourself — no install required.
  430. ### 5.1 Name Based Query
  431. ```bash
  432. witr node
  433. ```
  434. ```
  435. Target : node
  436. Process : node (pid 14233)
  437. User : deploy
  438. Command : node /srv/expense-manager/index.js
  439. Started : 2 days ago (Fri 2026-10-02 10:28:38 +00:00)
  440. Restarts : 3
  441. Why It Exists :
  442. systemd (pid 1) → PM2 v5.3.1: God (pid 5034) → node (pid 14233)
  443. Source : pm2-deploy.service (systemd)
  444. Description : PM2 process manager for user deploy (app: expense-manager)
  445. Unit File : /etc/systemd/system/pm2-deploy.service
  446. Working Dir : /srv/expense-manager
  447. Git Repo : expense-manager (main)
  448. Sockets : 127.0.0.1:5000 (TCP | LISTENING, 2 connections)
  449. 127.0.0.1:51744 → 127.0.0.1:5432 (TCP | ESTABLISHED)
  450. ```
  451. ---
  452. ### 5.2 Short Output
  453. ```bash
  454. witr --port 5000 --short
  455. ```
  456. ```
  457. systemd (pid 1) → PM2 v5.3.1: God (pid 5034) → node (pid 14233)
  458. ```
  459. ---
  460. ### 5.3 Tree Output
  461. ```bash
  462. witr --pid 40141 --tree
  463. ```
  464. ```
  465. systemd (pid 1)
  466. └─ sshd (pid 711)
  467. └─ sshd (pid 40122)
  468. └─ sshd (pid 40140)
  469. └─ bash (pid 40141)
  470. ├─ python3 (pid 8123)
  471. └─ ngrok (pid 14290)
  472. ```
  473. Note: _Tree view includes child processes (up to 10) and highlights the target process._
  474. ---
  475. ### 5.4 Multiple Matches
  476. ```bash
  477. witr ssh
  478. ```
  479. ```
  480. Multiple matching processes found:
  481. [1] sshd (pid 711)
  482. sshd: /usr/sbin/sshd -D [listener] 0 of 10-100 startups
  483. [2] ssh (pid 27311)
  484. ssh -l backup 10.0.4.20 rsync --server -logDtpre.iLsfxCIvu --partial . /backups/uploads/
  485. [3] sshd (pid 40122)
  486. sshd: deploy [priv]
  487. [4] sshd (pid 40140)
  488. sshd: deploy@pts/0
  489. Re-run with:
  490. witr --pid <pid>
  491. ```
  492. Names match as substrings, so `ssh` also finds every `sshd`. To match only processes named exactly `ssh`, use the `--exact` flag:
  493. ```bash
  494. witr ssh -x
  495. ```
  496. ---
  497. ### 5.5 File Based Query
  498. ```bash
  499. witr --file /var/lib/dpkg/lock
  500. ```
  501. ```
  502. Target : unattended-upgr
  503. Process : unattended-upgr (pid 33871)
  504. User : root
  505. Command : /usr/bin/python3 /usr/bin/unattended-upgrade --download-only
  506. Started : 4 min ago (Sun 2026-10-04 10:24:38 +00:00)
  507. Why It Exists :
  508. systemd (pid 1) → unattended-upgr (pid 33871)
  509. Source : apt-daily-upgrade.service (systemd)
  510. Description : Daily apt upgrade and clean activities
  511. Unit File : /lib/systemd/system/apt-daily-upgrade.service
  512. ```
  513. ---
  514. ### 5.6 Container Based Query
  515. ```bash
  516. witr --container api
  517. ```
  518. ```
  519. Target : gunicorn
  520. Process : gunicorn (pid 3141)
  521. User : root
  522. Container : docker: expense-manager-api-1 (id 7c41e0b9a2d3)
  523. Image : expense-manager-api:1.4.2
  524. Published : 0.0.0.0:8081->8080/tcp
  525. Compose File: /srv/expense-manager/docker-compose.yml
  526. Compose Dir : /srv/expense-manager
  527. Command : /usr/local/bin/python /usr/local/bin/gunicorn app:app --bind 0.0.0.0:8080 --workers 2
  528. Started : 5 days ago (Tue 2026-09-29 10:28:38 +00:00)
  529. Restarts : 1 (policy: unless-stopped)
  530. Why It Exists :
  531. systemd (pid 1) → containerd-shim (pid 3120) → gunicorn (pid 3141)
  532. Source : docker (container)
  533. Working Dir : /app
  534. Warnings :
  535. • Process is running as root
  536. • Container has no healthcheck configured
  537. ```
  538. Looks up a container by name, ID, image, command, or compose project/service across every detected runtime (Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, FreeBSD jails). The output includes the container's image and, for Compose services, the Compose file and project directory on the host. Pass `--verbose` to include mounts.
  539. ---
  540. ### 5.7 Multiple Inputs
  541. ```bash
  542. witr node --port 5432 --pid 8123
  543. ```
  544. ```
  545. ----- [name: node] -----
  546. Target : node
  547. Process : node (pid 14233)
  548. ...
  549. ----- [port: 5432] -----
  550. Target : postgres
  551. Process : postgres (pid 2010)
  552. ...
  553. ----- [pid: 8123] -----
  554. Target : python3
  555. Process : python3 (pid 8123)
  556. ...
  557. ```
  558. All target flags are repeatable and can be mixed. Results appear in the order you typed them. All output modes (`--short`, `--tree`, `--json`, `--env`, `--warnings`, `--verbose`) work with multiple inputs.
  559. ---
  560. ### 5.8 Warnings, Verbose and JSON
  561. Warnings close the standard report (see 5.6). `--warnings` shows only them:
  562. ```bash
  563. witr --pid 8123 --warnings
  564. ```
  565. ```
  566. Process : python3 (pid 8123)
  567. Command : python3 -m http.server 8000
  568. Warnings :
  569. • Process is listening on a public interface
  570. ```
  571. <details>
  572. <summary><strong><code>--verbose</code></strong>: adds memory, I/O, file descriptors and threads to the standard report</summary>
  573. <br>
  574. ```bash
  575. witr node --verbose
  576. ```
  577. ```
  578. ... (the report from 5.1)
  579. Memory:
  580. Virtual : 1.1 GB
  581. Resident : 179.0 MB
  582. Shared : 40.0 MB
  583. I/O Statistics:
  584. Read : 15.0 MB (2140 ops)
  585. Write : 4.0 MB (512 ops)
  586. File Descriptors: 34/1024
  587. Threads: 11
  588. ```
  589. </details>
  590. <details>
  591. <summary><strong><code>--json</code></strong>: the same report for scripts and AI agents (trimmed)</summary>
  592. <br>
  593. ```bash
  594. witr --port 5000 --json
  595. ```
  596. ```
  597. {
  598. "Target": { "Type": "port", "Value": "5000" },
  599. "ResolvedTarget": "node",
  600. "Process": {
  601. "PID": 14233,
  602. "PPID": 5034,
  603. "Command": "node",
  604. "Cmdline": "node /srv/expense-manager/index.js",
  605. "StartedAt": "2026-10-02T10:28:38Z",
  606. "User": "deploy",
  607. "WorkingDir": "/srv/expense-manager",
  608. "GitRepo": "expense-manager",
  609. "GitBranch": "main",
  610. "Sockets": [
  611. { "Port": 5000, "Address": "127.0.0.1", "State": "LISTEN", "Protocol": "TCP" },
  612. ...
  613. ],
  614. ...
  615. },
  616. "RestartCount": 3,
  617. "Ancestry": [
  618. { "PID": 1, "Command": "systemd", ... },
  619. { "PID": 5034, "Command": "PM2 v5.3.1: God", ... },
  620. { "PID": 14233, "Command": "node", ... }
  621. ],
  622. "Source": {
  623. "Type": "systemd",
  624. "Name": "pm2-deploy.service",
  625. "Description": "PM2 process manager for user deploy (app: expense-manager)",
  626. "UnitFile": "/etc/systemd/system/pm2-deploy.service",
  627. "Details": { "NRestarts": "3" }
  628. },
  629. "Warnings": null,
  630. ...
  631. }
  632. ```
  633. Every JSON shape is listed in [7.3 JSON Output](#73-json-output).
  634. </details>
  635. ---
  636. ## 6. Flags & Options
  637. ```
  638. -c, --container strings container(s) to look up (repeatable)
  639. --env show environment variables for the process
  640. -x, --exact use exact name matching (no substring search)
  641. -f, --file strings file(s) held open by a process (repeatable)
  642. -h, --help help for witr
  643. -i, --interactive interactive mode (TUI)
  644. --json show result as JSON
  645. --no-color disable colorized output
  646. -p, --pid strings pid(s) to look up (repeatable)
  647. -o, --port strings port(s) to look up (repeatable)
  648. -s, --short show only ancestry
  649. -t, --tree show only ancestry as a tree
  650. --verbose show extended process information
  651. -v, --version version for witr
  652. --warnings show only warnings
  653. ```
  654. Positional arguments (without flags) are treated as process or service names. Multiple names can be passed. By default, name matching uses substring matching (fuzzy search). Use `--exact` to match only processes with the exact name.
  655. All target flags (`--pid`, `--port`, `--file`, `--container`) are repeatable and can be mixed with each other and with positional name arguments. When multiple targets are provided, results are shown sequentially with labeled dividers. All output modes (standard, short, tree, JSON, env, warnings, verbose) work with multiple inputs.
  656. The `--container` flag searches across Docker, Podman, nerdctl, K8s/crictl, Incus, LXC, LXD, and FreeBSD jails, and matches against container name, image, command, and compose project/service labels, or a container ID (full, short, or a prefix of at least 4 characters).
  657. The TUI is launched if no arguments or relevant flags (`--pid`, `--port`, `--file`, `--container`) are provided, or if the `--interactive` flag is explicitly used. It needs a terminal: run without one (from a script, a pipe or CI) and witr exits with code 4 and asks for a target instead. An output mode with no target (`witr --json`, `--short`, `--tree`, `--warnings`, `--verbose` or `--env`) also exits with code 4 and asks for a target, rather than opening the TUI.
  658. ---
  659. ## 7. Output Behavior
  660. ### 7.1 Exit Codes
  661. witr returns meaningful exit codes for use in scripts, CI pipelines, and monitoring:
  662. | Code | Meaning |
  663. |------|---------|
  664. | 0 | Clean: process found, no warnings |
  665. | 1 | Warnings: process found but has one or more warnings |
  666. | 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) |
  667. | 3 | Permission denied: insufficient privileges (retry with sudo) |
  668. | 4 | Invalid input: bad arguments or ambiguous match |
  669. | 5 | Internal error: an unexpected failure occurred |
  670. | 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 |
  671. With several targets, the most severe result wins. Cause unknown ranks above warnings but below every failure (2 to 5).
  672. #### Example Usage:
  673. ```bash
  674. witr nginx --short
  675. case $? in
  676. 0) echo "All clear" ;;
  677. 1) echo "Warnings detected" ;;
  678. 2) echo "Process not running" ;;
  679. 3) echo "Need elevated privileges" ;;
  680. 4) echo "Invalid input or ambiguous match" ;;
  681. 5) echo "Internal error" ;;
  682. 6) echo "Cannot tell what started it" ;;
  683. esac
  684. ```
  685. ---
  686. ### 7.2 Standard Output Sections
  687. #### Target
  688. What the user asked about.
  689. #### Process
  690. Executable, PID, user, command, start time and restart count. The restart count comes from the managing system: a systemd unit, or the container runtime (Docker, Podman, nerdctl and Kubernetes), which also shows the container's restart policy, e.g. `Restarts : 12 (policy: unless-stopped)`.
  691. On Windows the user carries the process's integrity level when it isn't the normal Medium: `(elevated)` for a process run as administrator, `(system integrity)`, `(low integrity)` or `(untrusted integrity)` for sandboxed ones. On Linux, a `Security` line shows the AppArmor profile or SELinux context confining the process; unconfined processes have none.
  692. #### Why It Exists
  693. A causal ancestry chain showing how the process came to exist.
  694. This is the core value of witr.
  695. When the process that started it has exited, the chain marks the break with `? (original parent exited)` (or `? (parent pid N exited)` when that parent's PID no longer exists or now belongs to an unrelated process) instead of crediting whatever adopted it.
  696. #### Source
  697. The primary system responsible for starting or supervising the process (best effort).
  698. Examples:
  699. - systemd unit with schedule info for timer-triggered services (Linux)
  700. - launchd service with schedule/trigger details (macOS)
  701. - SSH session (with remote IP and terminal)
  702. - docker container
  703. - pm2
  704. - cron
  705. - interactive shell (detects tmux/screen sessions)
  706. - Snap/Flatpak sandbox (Linux)
  707. Only **one primary source** is selected. If the original parent has exited and nothing about the process itself (its container, service unit, login session or app scope, or launchd job) explains it, the source is reported as `unknown` rather than guessed. On systems without such a service manager it stays `init`, with a note that init only adopted it.
  708. #### Context (best effort)
  709. - Working directory
  710. - Git repository name and branch
  711. - Container name / image (docker, podman, kubernetes, colima, containerd)
  712. - Sockets: listeners first, each with the number of connections it accepted, then other sockets; a connection shows `local → remote`
  713. - Public vs private bind
  714. #### Warnings
  715. Non‑blocking observations:
  716. - Process is a zombie (defunct) or stopped (T state)
  717. - Process is using high CPU (>2h total) or high memory (>1GB RSS)
  718. - Process is listening on a public interface (0.0.0.0 / ::)
  719. - Process is running as root
  720. - Dangerous Linux capabilities on a non-root process (CAP_SYS_ADMIN, CAP_SYS_PTRACE, etc.)
  721. - Service or container has restarted more than 5 times
  722. - No known supervisor or service manager detected
  723. - Original parent process has exited, so what started the process can't be traced (shown instead of the one above)
  724. - Process has been running for over 90 days
  725. - Process is running from a suspicious working directory (`/`, `/tmp` or `/var/tmp`)
  726. - Container has no healthcheck configured
  727. - Service name and process name do not match
  728. - Process is running from a deleted binary
  729. - Library injection indicators (`LD_PRELOAD`, `DYLD_*`)
  730. ---
  731. ### 7.3 JSON Output
  732. `--json` is meant for scripts and tools, and its output is a contract:
  733. - **Stable:** field names, what they mean, and their types. Releases may add fields, so ignore any you don't recognise.
  734. - **Not part of the contract:** field order, whitespace, and the wording of human-readable text (`Error`, `Note`, `Description` and warning messages). Match on fields and exit codes, not on sentences.
  735. - **Empty values** may be `null`, an empty list, or left out.
  736. - **Breaking changes** (renaming, removing or retyping a field) only ship in a release whose notes call them out.
  737. | Command | Output |
  738. |---------|--------|
  739. | `witr <target> --json` | The full report: `Target`, `Process`, `Ancestry`, `Source`, `Warnings` and the rest |
  740. | `--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 |
  741. | `--tree --json` | `{Ancestry, Children}`, each a list of the same entries |
  742. | `--warnings --json` | `{PID, Process, Command, Warnings}` |
  743. | `--env --json` | `{PID, Process, Command, Env}` |
  744. | A container whose processes aren't visible | `{Target, Runtime, ContainerID, ContainerName, Image, …, Note}` |
  745. | A failed lookup | `{Target, Error}`, plus `Matches` when the target was ambiguous |
  746. | Several targets | A list of the above, one entry per target, in the order given |
  747. A test pins every field of every shape, so an accidental rename fails the build.
  748. ---
  749. ## 8. Platform Support
  750. - **Linux** (x86_64, arm64, loong64) - Full feature support (`/proc`).
  751. - **macOS** (x86_64, arm64) - Uses `ps`, `lsof`, `netstat`, `sysctl`, `launchctl`.
  752. - **Windows** (x86_64, arm64) - Native Win32 APIs (ToolHelp32, PSAPI, Service Control Manager). No PowerShell or WMI dependency.
  753. - **FreeBSD** (x86_64, arm64) - Uses `procstat`, `ps`, `sockstat`, `fstat`.
  754. ---
  755. ### 8.1 Feature Compatibility Matrix
  756. | Feature | Linux | macOS | Windows | FreeBSD | Notes |
  757. |---------|:-----:|:-----:|:-------:|:-------:|-------|
  758. | **Process Selection** |
  759. | By Name | ✅ | ✅ | ✅ | ✅ | |
  760. | By PID | ✅ | ✅ | ✅ | ✅ | |
  761. | By Port | ✅ | ✅ | ✅ | ✅ | |
  762. | By File | ✅ | ✅ | ✅ | ✅ | |
  763. | By Container | ✅ | ✅ | ✅ | ✅ | Requires the runtime CLI on PATH (docker/podman/nerdctl/crictl/incus/lxc/lxc-ls/jls). |
  764. | Multiple/mixed inputs | ✅ | ✅ | ✅ | ✅ | Repeatable flags, mixed types. |
  765. | Exact Match | ✅ | ✅ | ✅ | ✅ | |
  766. | Full command line | ✅ | ✅ | ✅ | ✅ | |
  767. | Process start time | ✅ | ✅ | ✅ | ✅ | |
  768. | Working directory | ✅ | ✅ | ✅ | ✅ | |
  769. | Environment variables | ✅ | ⚠️ | ⚠️ | ✅ | macOS: SIP restrictions; Windows: protected processes inaccessible. |
  770. | **Network** |
  771. | Listening ports | ✅ | ✅ | ✅ | ✅ | |
  772. | Connections (remote end) | ✅ | ✅ | ✅ | ✅ | Connections show their remote end; connections a listener accepted are counted on its row. |
  773. | Bind addresses | ✅ | ✅ | ✅ | ✅ | |
  774. | Port → PID resolution | ✅ | ✅ | ✅ | ✅ | |
  775. | 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. |
  776. | **Service Detection** |
  777. | Service Manager | ✅ | ✅ | ✅ | ✅ | Linux: systemd, macOS: launchd, Windows: Services, FreeBSD: rc.d |
  778. | Service Description | ✅ | ✅ | ✅ | ✅ | Linux: `Description`, macOS: `Comment`, Windows: `Display Name`, FreeBSD: `rc` header |
  779. | Configuration Source | ✅ | ✅ | ✅ | ✅ | Linux: Unit File, macOS: Plist, Windows: Registry Key, FreeBSD: Rc Script |
  780. | Supervisor | ✅ | ✅ | ✅ | ✅ | |
  781. | Containers | ✅ | ✅ | ✅ | ✅ | Docker (plus compose mappings), Podman, nerdctl, K8s (Kubepods/crictl), Containerd. Colima on macOS/Linux. Incus/LXC/LXD on Linux. Jails on FreeBSD. |
  782. | SSH session detection | ✅ | ✅ | ✅ | ✅ | Detects remote IP and terminal. |
  783. | tmux/screen detection | ✅ | ✅ | ❌ | ✅ | Shows session name in source. |
  784. | Schedule detection | ✅ | ✅ | ❌ | ❌ | Linux: systemd timers, macOS: launchd intervals/calendar. |
  785. | Restart count | ✅ | ⚠️ | ⚠️ | ❌ | systemd restarts on Linux; container restart count and policy wherever Docker, Podman, nerdctl or Kubernetes runs. |
  786. | 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. |
  787. | Snap/Flatpak detection | ✅ | ❌ | ❌ | ❌ | |
  788. | **Health & Diagnostics** |
  789. | CPU usage detection | ✅ | ✅ | ✅ | ✅ | |
  790. | Memory usage detection | ✅ | ✅ | ✅ | ✅ | |
  791. | Health status detection | ✅ | ✅ | ✅ | ✅ | |
  792. | Open Files / Handles | ✅ | ✅ | ⚠️ | ✅ | Windows: count only. |
  793. | File Locks | ✅ | ✅ | ❌ | ✅ | Linux: `/proc/locks`; macOS/FreeBSD: derived from `lsof`/`fstat`. |
  794. | Deleted binary detection | ✅ | ✅ | ✅ | ✅ | Warns if executable is missing. |
  795. | Capability warnings | ✅ | ❌ | ❌ | ❌ | Warns about dangerous capabilities on non-root processes. |
  796. | Security context | ✅ | ❌ | ✅ | ❌ | Linux: AppArmor profile or SELinux context; Windows: integrity level (elevated, system, low). |
  797. | **Context** |
  798. | Git repo/branch detection | ✅ | ✅ | ✅ | ✅ | |
  799. | **Interactive Mode (TUI)** |
  800. | Processes Tab | ✅ | ✅ | ✅ | ✅ | |
  801. | Ports Tab | ✅ | ✅ | ✅ | ✅ | |
  802. | Containers Tab | ✅ | ✅ | ✅ | ✅ | |
  803. | Locks Tab | ✅ | ✅ | ❌ | ✅ | Toggle (`a`) shows all open files. |
  804. | Process Details | ✅ | ✅ | ✅ | ✅ | |
  805. | Process Actions | ✅ | ✅ | ❌ | ✅ | |
  806. **Legend:** ✅ Full support | ⚠️ Partial/limited support | ❌ Not available
  807. ---
  808. ### 8.2 Permissions Note
  809. #### Linux/FreeBSD
  810. witr inspects system directories which may require elevated permissions.
  811. If you are not seeing the expected information, try running witr with sudo:
  812. ```bash
  813. sudo witr [your arguments]
  814. ```
  815. Without root, a port held by another user's process still shows which user it belongs to (`it belongs to postgres`), but not the process. With root, a port that no process on the system holds is reported as such (exit code 2): on WSL that's usually a process in another distro, since all distros share one network.
  816. #### macOS
  817. Some operations may require elevated permissions:
  818. ```bash
  819. sudo witr [your arguments]
  820. ```
  821. Note: Due to macOS System Integrity Protection (SIP), some system process details may not be accessible even with sudo.
  822. #### Windows
  823. On Windows, witr talks directly to Win32 APIs (ToolHelp32, PSAPI, Service Control Manager) rather than spawning PowerShell or WMI, so startup is fast and there's no `Get-CimInstance` hang. To see details for processes owned by other users or system services, you must run the terminal as **Administrator**.
  824. ```powershell
  825. # Run in Administrator PowerShell
  826. .\witr.exe [your arguments]
  827. ```
  828. ---
  829. ## 9. Sponsors
  830. Special thanks to the people who supported **witr** ❤️
  831. <p>
  832. <a href="https://github.com/timcolson" title="Tim Colson">
  833. <img src="https://images.weserv.nl/?url=github.com/timcolson.png&mask=circle&w=80&h=80" width="80">
  834. </a>
  835. <a href="https://github.com/R-Bose" title="Rijurekh Bose">
  836. <img src="https://images.weserv.nl/?url=github.com/R-Bose.png&mask=circle&w=80&h=80" width="80">
  837. </a>
  838. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.