Onboarding: avwo/whistle

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/avwo/whistle shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Single-maintainer risk — review before adopting

• Last commit 2d ago
• 4 active contributors
• MIT licensed
• CI configured
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 94% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live avwo/whistle repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/avwo/whistle.

What it runs against: a local clone of avwo/whistle — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in avwo/whistle | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>avwo/whistle</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of avwo/whistle. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/avwo/whistle.git
#   cd whistle
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of avwo/whistle and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "avwo/whistle(\\.git)?\\b" \\
  && ok "origin remote is avwo/whistle" \\
  || miss "origin remote is not avwo/whistle (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/avwo/whistle"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Whistle is a Node.js-based network debugging proxy that intercepts and modifies HTTP, HTTPS, HTTP/2, and WebSocket traffic in real-time. It provides a web UI (served from biz/webui/) for rule-based request/response manipulation, certificate management (bin/ca/), and integrated tools like Weinre (remote DOM inspection) and request composition, making it a complete alternative to Fiddler or Charles Proxy for cross-platform debugging. Monolithic structure: bin/ contains CLI entry points (whistle.js, proxy.js, ca/cli.js for cert management, plugin.js for extensibility); biz/webui/cgi-bin/ is the backend API handlers (~40+ .js files for rules, certs, cookies, data sync); assets/ holds frontend HTML/CSS/JS (log.js, weinre.js, worker.js); .babelrc and .eslintrc indicate ES6+ transpilation and linting standards.

Who it's for

Full-stack developers, QA engineers, and security researchers who need to inspect, mock, or modify live network traffic during development and testing—particularly those working with HTTPS/HTTP2 APIs, WebSockets, or who want to avoid vendor lock-in (it's open-source and runs on macOS, Windows, Linux, and headless servers).

Maturity & risk

Actively maintained and production-ready. The repo has 2.2M+ lines of JavaScript, established CI via .travis.yml, versioned releases (CHANGELOG.md exists with English + Chinese variants), and targets Node.js >=8. The desktop client (whistle-client) is officially recommended for non-CLI users, indicating a mature ecosystem around the core.

Single maintainer (avwo) visible in repo naming; no yarn.lock or npm shrinkwrap evident in file list, increasing supply-chain risk. The codebase is large (2.2MB JS) with complex proxy logic handling multiple protocols—bugs in certificate validation or request interception could expose traffic. No obvious test directory in top 60 files is a red flag for a security-critical tool.

Active areas of work

No recent commit data is visible in the provided file list, but the presence of versioned CHANGELOG files, .travis.yml for CI, and plugin/cert management endpoints (add-rules-values.js, create-cert.js, custom-handler.js) suggests active feature parity with commercial proxies. Desktop client (whistle-client) is being pushed as the primary installation method.

Get running

Clone and install: git clone https://github.com/avwo/whistle.git && cd whistle && npm install. Run the CLI: npm run dev or use bin/whistle.js start directly. For deployment, install globally: npm i -g whistle && w2 start (see bin/ for all CLI commands).

Daily commands: npm start or w2 start (requires installation). Proxy listens on default 8888. Web UI at http://localhost:8899. Headless: set environment variables for port configuration (check bin/proxy.js for details). For development: npm run dev rebuilds assets.

Map of the codebase

• bin/whistle.js: Main CLI entry point; orchestrates start/stop/status/ca/proxy commands
• bin/proxy.js: Core proxy server initialization; binds to 8888 and sets up HTTP/HTTPS/WebSocket listeners
• bin/ca/index.js: CA certificate management; generates and stores custom root certs for HTTPS interception
• biz/index.js: Business logic hub; coordinates rule matching, request interception, response transformation
• biz/webui/cgi-bin/get-data.js: Central API handler for fetching captured request/response logs to the web UI
• assets/js/log.js: Frontend logging component; displays intercepted traffic in the web UI dashboard
• .babelrc: ES6+ transpilation config; ensures compatibility across Node versions and older browsers

How to make changes

New rule/transformation: add a handler file in biz/webui/cgi-bin/ (follow pattern of add-rules-values.js). Certificate logic: modify bin/ca/index.js or bin/ca/cli.js. UI features: edit assets/tab.html, assets/modal.html, assets/js/. CLI commands: extend bin/ files (e.g., bin/proxy.js for proxy setup). Plugins: see bin/plugin.d.ts for interface; extensions go in ~/.whistle/plugins/.

Traps & gotchas

1. HTTPS requires CA cert: Clients must install Whistle's root CA (w2 ca) or traffic won't decrypt—easy to forget on first setup. 2. Port 8888/8899 conflicts: If ports are in use, proxy fails silently; check lsof -i :8888. 3. Rule syntax is custom: Not standard regex or glob patterns—see docs/rules for exact syntax, easy to misconfigure. 4. Plugin API not versioned: bin/plugin.d.ts exists but no semver guarantee; plugins may break across minor releases. 5. Cert storage is platform-specific: ~/.whistle/ on Unix, APPDATA/whistle on Windows—path assumptions in code.

Concepts to learn

• Man-in-the-Middle (MITM) with Custom CA — Whistle intercepts HTTPS by issuing certificates signed by its own CA; understanding certificate pinning bypass, trust store injection, and TLS handshake manipulation is essential to the core proxy mechanism.
• HTTP/2 Server Push & Multiplexing — Whistle supports HTTP/2 traffic; HTTP/2 uses binary framing and stream multiplexing over a single connection, fundamentally different from HTTP/1.1 chunked encoding.
• WebSocket Tunneling & Frame Interception — WebSocket upgrade handshake and frame-level inspection (opcode, payload masking) require different handling than HTTP request/response pairs; Whistle must buffer and transform frames.
• Rule Engine Pattern Matching — Whistle's rule syntax (in biz/webui/cgi-bin/add-rules-values.js) maps URL patterns to transformations; understanding rule precedence, regex scoping, and caching is critical for rule debugging.
• Plugin Hook System & AST Rewriting — Plugins can hook into request/response lifecycle (bin/plugin.js); understanding middleware chaining, async hooks, and request body streaming prevents plugin conflicts and performance issues.
• Certificate Pinning & Trust Store Override — HTTPS clients may pin certificates to prevent MITM; Whistle must either convince clients to trust its CA (OS-level trust store injection via bin/ca/) or bypass pinning, which varies by platform and framework.
• Stream Buffering & Memory Management for Proxy — Proxies must buffer request/response bodies for rule matching and logging (get-data.js); streaming large files naively causes memory bloat—Whistle likely uses streams with backpressure handling.

Related repos

• mitmproxy/mitmproxy — Python-based network proxy with similar interception + replay features; good reference for protocol handling patterns and UI design alternatives.
• avwo/whistle-client — Official desktop wrapper for Whistle; the recommended installation method for macOS/Windows/Linux users—understanding this companion repo is essential for end-user docs.
• searxng/searxng — Unrelated, but avwo likely uses similar Node.js proxy patterns; good reference for scaling proxy logic across multiple protocol types.
• nodejs/node — Core runtime; Whistle relies heavily on Node.js net/http/https/tls modules—version compatibility (>=8) is critical for CA and MITM logic.
• weinre/weinre — Remote debugging framework bundled into Whistle (assets/js/weinre.js); understanding its architecture is key to Whistle's DOM inspection feature.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for biz/webui/cgi-bin request handlers

The cgi-bin directory contains 30+ handler files (abort.js, add-rules-values.js, create-cert.js, etc.) with no visible test suite in the file structure. These are critical request handlers for the web UI that manipulate proxy rules, certificates, and plugins. Adding unit tests would improve reliability and prevent regressions when modifying core functionality.

• [ ] Create test/cgi-bin/ directory structure mirroring biz/webui/cgi-bin/
• [ ] Write tests for certificate handlers (certs/active.js, create-cert.js, upload.js) covering edge cases like invalid cert formats
• [ ] Write tests for rules handlers (rules/* files) validating rule parsing and persistence
• [ ] Write tests for plugin handlers (plugins/*.js) covering install/uninstall/enable workflows
• [ ] Add test coverage reporting to package.json scripts

Add TypeScript definition files for core biz/ and bin/ modules

The repo has some .d.ts files (bin/ca/index.d.ts, bin/plugin.d.ts) but the main biz/index.js and proxy initialization logic lack type definitions. This makes it harder for plugin developers and external tools to integrate with whistle programmatically. Adding comprehensive type definitions would improve DX and enable IDE autocomplete.

• [ ] Create biz/index.d.ts defining exports from biz/index.js and biz/init.js
• [ ] Create bin/proxy.d.ts for proxy initialization and configuration types
• [ ] Create types for the webui handler interface (expected signature for cgi-bin scripts)
• [ ] Update existing bin/ca/index.d.ts and bin/plugin.d.ts if incomplete
• [ ] Add reference to .d.ts files in package.json 'types' field

Add integration tests for HTTP/2 and WebSocket proxying with HTTP/1.1 fallback

The file structure shows enable-http2.js handler and assets/js/worker.js suggesting WebSocket support, but there's no visible test suite validating protocol handling, upgrade logic, or fallback behavior. This is critical for a proxy tool that advertises HTTP/2 and WebSocket debugging. Integration tests would validate end-to-end protocol handling.

• [ ] Create test/integration/http2-proxy.test.js with tests for HTTP/2 request proxying and stream handling
• [ ] Create test/integration/websocket-proxy.test.js validating WebSocket upgrade, frame handling, and fallback to HTTP/1.1
• [ ] Test the enable-http2.js handler (biz/webui/cgi-bin/enable-http2.js) to verify protocol negotiation
• [ ] Add tests for mixed protocol scenarios (HTTP/1.1 client → HTTP/2 server)
• [ ] Integrate tests into .travis.yml CI pipeline

Good first issues

• Add unit tests for bin/ca/index.js (certificate generation logic)—currently no test/ directory visible; even basic Jest tests for cert validation would improve maintainability.
• Document the rule matching engine (likely in biz/index.js) with inline examples—new contributors struggle to understand rule precedence and syntax without internal docs.
• Create TypeScript type definitions for the plugin API (bin/plugin.d.ts exists but is sparse)—expand it to cover all hook points and request/response object shapes to reduce plugin author friction.

Top contributors

• @avwo — 94 commits
• @echopi — 4 commits
• @md-frank — 1 commits
• @sroucheray — 1 commits

Recent commits

• a154c50 — test: change wsPort from 8081 to 18081 to avoid conflicts (echopi)
• 3f2c89f — test: regenerate test certs with 2048-bit keys (echopi)
• 2787459 — docs: address review feedback on Linux cert instructions (echopi)
• f1902b8 — docs: add Linux certificate installation instructions including Alpine (echopi)
• 14a9407 — fix: add authorityKeyIdentifier extension to fix Python SSL verification error (md-frank)
• afe1a10 — Release v2.10.2 (avwo)
• b55839b — feat: refine Tools/Console (avwo)
• 3bd6f0c — Release v2.10.2 (avwo)
• f90fab3 — refactor: refine code (avwo)
• b96d01f — docs: update (avwo)

Security observations

• High · Missing Dependency Information — package.json (not provided). The package.json or dependency manifest was not provided for analysis. Without visibility into direct and transitive dependencies, it's impossible to assess for known vulnerabilities, outdated packages, or insecure library versions that could be exploited. Fix: Provide package.json and package-lock.json for dependency vulnerability scanning. Use npm audit, OWASP Dependency-Check, or Snyk to identify and remediate vulnerable dependencies regularly.
• High · HTTPS/TLS Interception Proxy Functionality — bin/ca/, biz/webui/cgi-bin/certs/. Whistle is designed as a debugging proxy that intercepts HTTPS traffic and creates certificates. While legitimate for development, the presence of CA certificate generation and HTTPS interception capabilities (bin/ca/index.js, biz/webui/cgi-bin/certs/upload.js, biz/webui/cgi-bin/certs/active.js) creates significant security risks if deployed in untrusted environments or misconfigured, potentially enabling man-in-the-middle attacks. Fix: Ensure this tool is only deployed in controlled development environments. Implement strict access controls, require authentication for certificate management endpoints, and document HTTPS interception limitations. Warn users against using in production environments.
• High · Web UI File Upload Endpoint — biz/webui/cgi-bin/certs/upload.js. The file biz/webui/cgi-bin/certs/upload.js indicates certificate file upload functionality. Without examining the code, there's a risk of arbitrary file upload vulnerabilities, path traversal, or file overwrite attacks if input validation is insufficient. Fix: Implement strict file type validation (whitelist approach), verify file signatures, enforce file size limits, sanitize filenames, store uploads outside web root, use randomized filenames, and implement CSRF protection on upload endpoints.
• High · Custom Certificate/Plugin Handling — biz/webui/cgi-bin/get-custom-certs-files.js, biz/webui/cgi-bin/get-custom-certs-info.js, biz/webui/cgi-bin/plugins/. Multiple endpoints handle custom certificates (get-custom-certs-files.js, get-custom-certs-info.js) and plugins (biz/webui/cgi-bin/plugins/). Custom plugin execution could lead to arbitrary code execution if plugins are not properly validated and sandboxed. Fix: Implement strict validation and sandboxing for plugin execution. Use code signing for plugins, maintain a plugin whitelist, execute plugins in isolated processes, and implement resource quotas. Document plugin security policies clearly.
• Medium · Potential Command Injection in bin/ Utilities — bin/plugin.js, bin/import.js, bin/use.js. Files like bin/plugin.js, bin/import.js, and bin/use.js suggest CLI command handling and external command execution. Without code review, these could be vulnerable to command injection if user input is not properly escaped. Fix: Use parameterized execution methods (child_process.execFile instead of exec), validate all user inputs against strict whitelists, avoid shell string interpolation, and implement least privilege execution contexts.
• Medium · Session Management Security — biz/webui/cgi-bin/get-session.js. The endpoint biz/webui/cgi-bin/get-session.js handles session data. Session tokens should be cryptographically secure, have appropriate expiration, and be transmitted securely. Missing HTTPOnly/Secure flags could expose sessions to XSS. Fix: Ensure session tokens use cryptographically secure random generation (minimum 256 bits entropy), set HTTPOnly and Secure flags on session cookies, implement appropriate session timeouts, use SameSite cookie attribute, and validate session integrity.
• Medium · Missing CORS and Security Headers Configuration — biz/webui/cgi-bin/. The WebUI endpoints (biz/webui/cgi-bin/) handle sensitive operations (certificate management, rules modification, plugin installation). Without evidence of proper CORS policies, CSRF tokens, and security headers, the application may be vulnerable to cross-origin attacks. Fix: Implement strict CORS policies restricting to localhost/specific origins, add CSRF token validation on state-changing

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.