PingSherpa

by shrenixcodes

Find the lag. Understand the cause.

PingSherpa is a local-first Windows desktop utility for diagnosing the network side of a bad gaming session: high ping, jitter, packet loss, Wi-Fi instability, slow DNS and unhappy routing. It tries to answer three questions, in plain English:

1. What is wrong with the connection?
2. What evidence suggests that?
3. What can be safely done about it?

No Python installation is required. The installer ships a standalone Windows build. The installer is unsigned at this stage of the project, so Windows SmartScreen may show a warning on first run — the usual "More info → Run anyway" flow applies.

---

What it measures

• RTT to the local gateway, several neutral public endpoints, and an optional user-supplied target (your game server, for example).
• Jitter, defined as mean |RTT[i] − RTT[i-1]| (Packet Delay Variation). The calculation is documented in analysis/metrics.py and never conflated with standard deviation.
• Packet loss computed from actual probes, shown alongside the sample count so a 20 % loss over five pings reads differently than over fifty.
• DNS lookup timing and failures through dnspython.
• Route information via Windows tracert.
• Wi-Fi signal, channel, band and link rates via netsh wlan show interfaces.
• Adapter state and traffic counters via psutil.

Nothing probes automatically. The Overview screen opens with "Not measured" placeholders until you click Run Diagnosis. A gaming utility that scans the network every time it opens is exactly what gamers don't want running.

How it explains findings

The analysis layer has a small set of evidence-based rules. A rule only fires when two independent signals line up — for example, high gateway RTT and weak Wi-Fi signal. Every finding is tagged with its severity, the measurements that triggered it, likely cause, alternative explanations, a recommended next step and a verification method.

A local Isolation Forest catches unusual observations once enough history has accumulated. The model is CPU-only, trained locally, and refuses to run until it has 50 real samples to work with. Network diagnosis works fully without ML — the anomaly detector is advisory, not required.

Safe remediation

Nothing changes on the system without an explicit confirmation dialog. The v0.1 action catalogue is deliberately small:

• Flush the DNS resolver cache.
• Open Windows network / Wi-Fi settings.
• Release and renew the DHCP lease.

Each action is executed with an argument list and shell=False, with bounded timeouts, and verified by re-measuring afterwards. A zero exit code is not treated as proof the problem went away.

Installation

Installer (recommended)

1. Download PingSherpa-Setup-vX.Y.Z-x64.exe from the latest release.
2. Run it. The installer is per-user and does not require administrator rights.
3. Launch PingSherpa from the Start Menu.

Uninstalling leaves your history intact under %LOCALAPPDATA%\PingSherpa\pingsherpa.sqlite. Delete that folder to clear it, or use the Clear button on the History screen.

Portable ZIP

1. Download PingSherpa-Portable-vX.Y.Z-x64.zip from the same release.
2. Extract anywhere.
3. Run pingsherpa.exe.

Checksums

Each release also ships SHA256SUMS.txt. Verify with PowerShell:

Get-FileHash .\PingSherpa-Setup-v0.1.0-x64.exe -Algorithm SHA256

Privacy

• No account, no cloud sync, no telemetry.
• Measurements stay on your computer under %LOCALAPPDATA%\PingSherpa.
• Report export is user-initiated and redacts local-network details.
• Wi-Fi passwords and arbitrary network traffic are never captured.

Development

Requires Python 3.12.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

pytest -q
python -m pingsherpa.main

See docs/architecture.md for the layering and the design decisions behind the probing and analysis layers.

Packaging

The Windows release pipeline runs pyside6-deploy-style Nuitka standalone, wraps the output in an NSIS installer, also produces a portable ZIP, and attaches SHA-256 checksums to a GitHub release.

Tagging a version triggers the pipeline:

git tag -a v0.1.0 -m "PingSherpa v0.1.0"
git push origin v0.1.0

Both workflows live in .github/workflows/. The release workflow validates that the pushed tag matches [project.version] in pyproject.toml before it builds anything.

Limitations

• Windows 10 and 11, x64 only.
• Game server IPs are supplied by the user — PingSherpa does not inspect running games or their private network traffic.
• The installer is unsigned at this stage; expect a SmartScreen prompt.
• Anomaly detection is gated on 50+ real observations.
• icmplib cannot always open an ICMP socket on Windows; PingSherpa silently falls back to ping.exe output parsing.

Third-party notices

See THIRD_PARTY_NOTICES.md for the libraries and the icon paths (Lucide, ISC) that ship with PingSherpa.

License

MIT. See LICENSE.