From 47f52e16df3a7ad7a50b1e650b280b612bc53aae Mon Sep 17 00:00:00 2001 From: Yunare Maia Date: Sun, 9 Aug 2026 17:36:39 +0000 Subject: [PATCH 1/2] docs: add 'Using witr with AI Agents' section AI coding agents hit port-in-use, zombie servers and container confusion during local dev; they chain lsof/ps/netstat/docker ps manually. witr already fixes this via --json but the README never said so. Add section 8 with an AGENTS.md/CLAUDE.md snippet (port, process, and container queries with --json), an optional Claude Code slash command, and a short rationale for not wrapping witr in MCP (shell access + --json is already the one-line structured call). Renumber sections 9-11. Signed-off-by: Yunare Maia --- README.md | 44 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5e6aaea..3d71463 100644 --- a/README.md +++ b/README.md @@ -823,7 +823,45 @@ Non‑blocking observations such as: --- -## 8. Platform Support +## 8. Using witr with AI Agents + +AI coding agents (Claude Code, Codex, Cursor, etc.) constantly hit port-in-use +errors, zombie servers, and container confusion during local development. +Instead of chaining `lsof` / `ps` / `netstat` / `docker ps` manually, point the +agent at witr — the causal chain, source and warnings come back in one call. + +`--json` is the machine-output flag: a single structured line the agent can +parse directly. Exit codes are already scriptable (see [7.2 Exit Codes](#72-exit-codes)). + +### AGENTS.md / CLAUDE.md snippet + +Add this to your project's agent instructions: + +```markdown +Process/port debugging: use witr before manual lsof/ps/netstat chains. +- Port conflict: witr --port --json +- Stuck process: witr --json or witr --pid --tree +- Container issue: witr --container --verbose --json +``` + +### Claude Code slash command (optional) + +Save as `.claude/commands/witr.md` in your project: + +```markdown +Run `witr $ARGUMENTS --json` and summarize the causal chain, source, and any +warnings (e.g. running as root, public interface, deleted binary). +``` + +### Why not an MCP wrapper? + +Claude Code, Codex and similar agents already have shell access — `witr --json` +is the one-line structured call. An MCP server would only reimplement it with +extra protocol overhead. This is a discoverability gap, not a missing feature. + +--- + +## 9. Platform Support - **Linux** (x86_64, arm64) - Full feature support (`/proc`). - **macOS** (x86_64, arm64) - Uses `ps`, `lsof`, `sysctl`, `pgrep`. @@ -918,7 +956,7 @@ On Windows, witr talks directly to Win32 APIs (ToolHelp32, PSAPI, Service Contro --- -## 9. Success Criteria +## 10. Success Criteria witr is successful if: @@ -929,7 +967,7 @@ witr is successful if: --- -## 10. Sponsors +## 11. Sponsors Special thanks to the people who supported **witr** ❤️ From f378f3e2f5505986fb003f34955cbd31b6a96ff5 Mon Sep 17 00:00:00 2001 From: Yunare Maia Date: Tue, 11 Aug 2026 20:25:44 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20drop?= =?UTF-8?q?=202=20sections,=20expand=20.md=20snippet,=20fix=20numbering?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per maintainer review (#224): - Remove 'Claude Code slash command (optional)' and 'Why not an MCP wrapper?' - Expand the AGENTS.md/CLAUDE.md snippet with the structured output contract (--json shape, exit codes incl. 2 = no match, --help pointer) - Renumber: 8.1 Feature Compatibility Matrix -> 9.1 (Platform Support is now 9) Signed-off-by: Yunare Maia --- README.md | 22 +++++++--------------- 1 file changed, 7 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 3d71463..97e7299 100644 --- a/README.md +++ b/README.md @@ -844,20 +844,12 @@ Process/port debugging: use witr before manual lsof/ps/netstat chains. - Container issue: witr --container --verbose --json ``` -### Claude Code slash command (optional) - -Save as `.claude/commands/witr.md` in your project: - -```markdown -Run `witr $ARGUMENTS --json` and summarize the causal chain, source, and any -warnings (e.g. running as root, public interface, deleted binary). -``` - -### Why not an MCP wrapper? - -Claude Code, Codex and similar agents already have shell access — `witr --json` -is the one-line structured call. An MCP server would only reimplement it with -extra protocol overhead. This is a discoverability gap, not a missing feature. +The output is structured for machine consumption: `--json` emits one line with +the full process tree (pid, parent, command, user), the resolved cause, and any +warnings (running as root, public interface, deleted binary, container +mismatch). Non-zero exit codes signal the outcome — 2 for "no match found", so +an agent can branch on empty-vs-found without parsing prose. Run `witr --help` +for the complete flag list. --- @@ -870,7 +862,7 @@ extra protocol overhead. This is a discoverability gap, not a missing feature. --- -### 8.1 Feature Compatibility Matrix +### 9.1 Feature Compatibility Matrix | Feature | Linux | macOS | Windows | FreeBSD | Notes | |---------|:-----:|:-----:|:-------:|:-------:|-------|