Skip to content

docs: add 'Using witr with AI Agents' section #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
yunaremaia wants to merge 2 commits into from
Closed

docs: add 'Using witr with AI Agents' section #224

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
47f52e1
docs: add 'Using witr with AI Agents' section
yunaremaia Aug 9, 2026
f378f3e
docs: address review — drop 2 sections, expand .md snippet, fix numbe…
yunaremaia Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 34 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -823,7 +823,37 @@ 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 <PORT> --json
- Stuck process: witr <name> --json or witr --pid <PID> --tree
- Container issue: witr --container <name> --verbose --json
```

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.

---

## 9. Platform Support

- **Linux** (x86_64, arm64) - Full feature support (`/proc`).
- **macOS** (x86_64, arm64) - Uses `ps`, `lsof`, `sysctl`, `pgrep`.
Expand All @@ -832,7 +862,7 @@ Non‑blocking observations such as:

---

### 8.1 Feature Compatibility Matrix
### 9.1 Feature Compatibility Matrix

| Feature | Linux | macOS | Windows | FreeBSD | Notes |
|---------|:-----:|:-----:|:-------:|:-------:|-------|
Expand Down Expand Up @@ -918,7 +948,7 @@ On Windows, witr talks directly to Win32 APIs (ToolHelp32, PSAPI, Service Contro

---

## 9. Success Criteria
## 10. Success Criteria

witr is successful if:

Expand All @@ -929,7 +959,7 @@ witr is successful if:

---

## 10. Sponsors
## 11. Sponsors

Special thanks to the people who supported **witr** ❤️

Expand Down