feat: add network command to browser-tools

[mvanhorn]

Summary

Agents driving the DevTools-attached Chrome from browser-tools.ts can now tail network traffic the same way they tail console output. bun scripts/browser-tools.ts network --follow prints [REQ ], [RESP], and [FAIL] lines as puppeteer reports them, with the same --port, --types, --follow, --timeout, --color, --no-color flag set as the existing console subcommand.

Why this matters

console (PR #1) is the proven shape for tailing a CDP event stream from this script. Network traffic is the natural sibling event source: debugging XHR/fetch behavior currently means switching to another tool or running raw eval against the page. Mirroring console keeps the surface symmetric and the implementation under ~125 lines.

Resource-type filter accepts puppeteer's resourceType() enum: document, stylesheet, image, media, font, script, xhr, fetch, manifest, plus a few less common values. websocket is intentionally omitted from the help example because puppeteer's request and response events report only the WS upgrade handshake (frame traffic needs raw Network.webSocketFrameSent / Received via CDP). The help description carries a one-liner for users who try --types websocket anyway.

Output format:

• [REQ ] cyan, method (6-wide), resourceType (9-wide), URL
• [RESP] status-colored (green 2xx, yellow 3xx, red 4xx/5xx), status (6-wide), resourceType (9-wide), URL, gray (Nms) duration
• [FAIL] red, method, resourceType, URL, red error reason

Per-request timing uses WeakMap<HTTPRequest, number> keyed by the puppeteer request object, not URL+method, so parallel same-endpoint requests don't collide and the Map cleans up under --follow.

Demo

Live capture from pre-PR smoke testing: bun scripts/browser-tools.ts network --types document,script,image --timeout 3 against a navigation to https://www.wikipedia.org/. 13 real network events.

Testing

No automated test suite for browser-tools.ts (consistent with the rest of the file). Manual smoke:

bun scripts/browser-tools.ts start --port 9222
bun scripts/browser-tools.ts nav https://example.com
bun scripts/browser-tools.ts network --types xhr,fetch --follow
bun scripts/browser-tools.ts network --timeout 3
bun scripts/browser-tools.ts kill --ports 9222 --force

CHANGELOG entry left for maintainer copy on merge per AGENTS.MD ("Contributor PR authors should not edit changelog; maintainer/AI adds entry at merge"). Suggested line:

## YYYY-MM-DD - Network Traffic Capture
- Added `network` command to `scripts/browser-tools.ts` for capturing and tailing Chrome DevTools network traffic with resource-type filtering, continuous follow mode, configurable timeouts, and concise method/status/URL/duration formatting.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed May 25, 2026, 11:24 AM ET / 15:24 UTC.

Summary
Adds a network subcommand to scripts/browser-tools.ts that tails Puppeteer request, response, and failure events with resource-type filters, timeout/follow modes, and colored terminal output.

Reproducibility: not applicable. this is a new CLI feature rather than a bug report. The PR body includes an inspected terminal GIF proving the new command emits real network events.

Review metrics: 1 noteworthy metric.

• Diff scope: 1 file changed, 124 additions, 1 deletion. The feature is contained to the existing browser-tools CLI with no dependency, workflow, or package metadata changes.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Maintainers can rerun the PR body's smoke commands if they want local confirmation before merge.

Risk before merge

• No local Bun/Chrome smoke was run during this read-only review, so maintainers may still want to repeat the PR body's manual smoke commands before merge.

Maintainer options:

1. Decide the mitigation before merge
   Merge the scoped command if maintainers want this browser-tools surface, with the maintainer-owned changelog entry handled at landing time.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge
No repair lane needed; the patch is narrow and this review found no actionable code defect, so the remaining action is maintainer merge judgment.

Security
Cleared: No concrete security or supply-chain concern found; the diff adds local Puppeteer event listeners and terminal output without dependency, workflow, permission, or secret-handling changes.

Review details

Best possible solution:

Merge the scoped command if maintainers want this browser-tools surface, with the maintainer-owned changelog entry handled at landing time.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a new CLI feature rather than a bug report. The PR body includes an inspected terminal GIF proving the new command emits real network events.

Is this the best way to solve the issue?

Yes: adding one Puppeteer event-stream command next to the existing console command is the narrowest maintainable path I saw. No duplicate built-in network capture command exists on current main.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against ab2f2a8de00e.

Label changes

Label changes:

• add P3: This is a low-risk helper CLI feature with narrow scope and no evidence of an urgent broken workflow.
• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes an inspected GIF recording that directly shows the new command printing real network request and response output.
• add proof: 🎥 video: Contributor real behavior proof includes video or recording evidence. The PR body includes an inspected GIF recording that directly shows the new command printing real network request and response output.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (recording): The PR body includes an inspected GIF recording that directly shows the new command printing real network request and response output.

Label justifications:

• P3: This is a low-risk helper CLI feature with narrow scope and no evidence of an urgent broken workflow.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (recording): The PR body includes an inspected GIF recording that directly shows the new command printing real network request and response output.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes an inspected GIF recording that directly shows the new command printing real network request and response output.
• proof: 🎥 video: Contributor real behavior proof includes video or recording evidence. The PR body includes an inspected GIF recording that directly shows the new command printing real network request and response output.

Evidence reviewed

What I checked:

• PR diff scope: The merge result adds network at lines 584-704 with --port, --types, --follow, --timeout, color flags, and request/response/failure listeners. (scripts/browser-tools.ts:584, f97132a720ce)
• Current main lacks the command: Current main documents scripts/browser-tools.ts common commands without network, and source search found only the existing console/navigation/content network-idle usage, not a network capture command. (README.md:78, ab2f2a8de00e)
• Real behavior proof inspected: The linked GIF was downloaded to the allowed proof scratch area; ffprobe reports a 1244x476, 12-second recording, and the contact sheet shows bun scripts/browser-tools.ts network --types document,script,image --timeout 3 printing real [REQ] and [RESP] lines for wikipedia.org.
• Repository policy applied: AGENTS.MD says PR refs should be inspected through gh pr view/diff where available and contributor PR authors should not edit changelogs; no changelog finding was raised. (AGENTS.MD:45, ab2f2a8de00e)
• Related feature history: The existing console command this PR mirrors was introduced by commit ea0e72062947620a5dfe518d72b8b989d8111609, while the current main browser-tools file was last consolidated in bbc60ce6679333c43fab193a1fda5ce7b9961a86. (scripts/browser-tools.ts:410, ea0e72062947)

Likely related people:

• Peter Steinberger: Current main's scripts/browser-tools.ts and README browser-tools documentation are attributed to recent commits by this author, including the file consolidation and adjacent browser-tools additions. (role: recent area contributor; confidence: high; commits: bbc60ce66793, 03c9b8793e21, 35355d0d3bae; files: scripts/browser-tools.ts, README.md)
• srigi: Introduced the existing console capture command that this PR intentionally mirrors for network events. (role: adjacent feature introducer; confidence: medium; commits: ea0e72062947; files: scripts/browser-tools.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.