proxy-path-doctor 0.7.0

A read-only CLI for diagnosing mismatched proxy configuration sources.

proxy-path-doctor

proxy-path-doctor is a small, privacy-conscious, read-only CLI for diagnosing conflicting proxy configuration sources. It collects the settings that commonly cause confusing network failures, highlights mismatches, and produces a report that is safe to share in an issue.

The project is currently an early MVP. It supports Windows system proxy inspection, GNOME desktop proxy inspection on Linux, and portable checks for proxy environment variables, VS Code and Cursor user proxy settings, DNS, and optional HTTP connectivity.

Why this exists

Network failures are often reported as "the proxy looks correct" while several independent settings are involved. proxy-path-doctor gathers those signals in one place and redacts credentials before printing them.

The tool does not modify proxy settings, manage proxy servers, or choose a proxy provider. Its focus is explaining which configuration path a program may be using across Windows, Linux, environment variables, and connectivity checks.

Guides

• Why development proxy problems are hard to debug
• Troubleshooting Codex behind proxies

Install

Install the latest release from PyPI:

python -m pip install proxy-path-doctor

For development, install the project from the repository:

git clone https://github.com/oneAI6/proxy-doctor.git
cd proxy-doctor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Usage

Inspect local settings without sending a network request:

proxy-path-doctor

Include a DNS and HTTP connectivity check:

proxy-path-doctor --check-url https://example.com

Check whether a local development URL is covered by NO_PROXY:

proxy-path-doctor --check-url http://localhost:3000

Focus the report on Codex, VS Code, Cursor, and MCP proxy troubleshooting:

proxy-path-doctor --profile codex --check-url http://localhost:3000

Generate a JSON report for an issue:

proxy-path-doctor --format json --output proxy-report.json

Any username or password embedded in a proxy URL is replaced with ***. Review a generated report before posting it publicly because hostnames and proxy addresses may still describe your environment.

Testing feedback wanted

Real-world proxy setups vary widely. Windows and Linux users who rely on proxies for development tools, package managers, IDEs, or AI coding tools are invited to try the CLI and share whether its findings are clear and useful. See the testing feedback issue for a short checklist. A successful run with no conflict found is useful too.

Current checks

• Operating system and Python version
• Common proxy environment variables
• Windows user proxy settings
• Windows WinHTTP proxy settings
• Linux GNOME desktop proxy settings through gsettings
• VS Code and Cursor user proxy settings, including http.proxy and http.noProxy
• Optional DNS resolution
• Optional HTTP HEAD request with a timeout
• NO_PROXY matching for checked URLs, including domains, ports, and IP addresses
• Actionable findings for conflicting settings and connectivity failures
• A Codex-focused profile for IDE and MCP proxy troubleshooting

Example finding

[findings]
- WARNING: Proxy environment variables are set while the Windows user proxy is
  disabled. Suggestion: Check whether your terminal, IDE, or launcher exports
  HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY intentionally.

Contributing

Bug reports and focused pull requests are welcome. See CONTRIBUTING.md and docs/ROADMAP.md. The maintainer plan describes a realistic path from the MVP to a maintained public project. Release notes are available in CHANGELOG.md.

License

MIT