#223·witr

[Docs] Add "Using witr with AI coding agents" section (Claude Code, Codex, etc.)

Author: AkashPriyadarshiiCreated Aug 8, 2026Updated Aug 11, 2026

witr agents constantly hit port-in-use, zombie servers, container confusion during local dev. They chain lsof/ps/netstat/docker ps manually. witr already fixes this via --json. README doesn't mention it. Nobody finds it.

Add "Using witr with AI agents" section to README:

--json is the machine-output flag. State that explicitly.

AGENTS.md / CLAUDE.md snippet:

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

Optional Claude Code slash command (.claude/commands/witr.md):

Run witr $ARGUMENTS --json and summarize the causal chain, source, warnings.

MCP wrapper: not needed. Claude Code/Codex already have shell access. --json is already the one-line structured call. MCP would just reimplement it with extra protocol overhead.

Exit codes already scriptable, --json already exists. This is a discoverability gap, not a missing feature. Can PR if direction's fine.