v1.0.21 · built 2026-10-19T05:27:21Z

Lag Lens

A parallel network-lag witness you run on a computer wired to your Xfinity XB7 while you game. It probes the gateway, the Comcast hops and the internet several times a second, detects and classifies lag episodes, and writes a self-contained report you can show Comcast.

Install in two commands Download lag-lens.zip

Install

Open a terminal on the computer that is plugged into the XB7 and run these two commands.

1. Download and install to ~/lag-lens
curl -fsSL https://magitekzed.github.io/lag-lens/get.sh | sh
2. Start it
cd ~/lag-lens && bash start.sh

The installer verifies the download against its SHA-256 before unpacking, keeps a previous install as ~/lag-lens.old, and carries over your config.json and sessions/. No sudo, no pip, nothing is added to your PATH or startup items.

Download

Download lag-lens.zip
Version
1.0.21
Built
2026-10-19T05:27:21Z
SHA-256
88392627486d8d040ef180e8921897d3aca785847bdbf7c187392ebd473bb546

Also: lag-lens.zip.sha256 · version.json · get.sh

Manual install

  1. Download lag-lens.zip (button above) and unzip it. You get a lag-lens/ folder; put it wherever you like, for example your home folder.
  2. Optional: check the download. shasum -a 256 lag-lens.zip (macOS) or sha256sum lag-lens.zip (Linux) should print the hash shown above.
  3. Open a terminal in that folder and run bash start.sh.

Requirements

What you'll see

In the terminal

A quick self-check (which probes work, which gateway was found, whether the XB7 login succeeded), then a one-line status ticker that updates every second: gateway, Comcast hop and internet latency, loss, and the current verdict. The URL of the dashboard is printed next to a QR code so you can open it on your phone. Press Enter any time lag happens to drop a mark.

In the browser

A dashboard at http://<your-computer>:8787/ with live timelines for every target, the path ladder (your PC → XB7 → Comcast hops → internet), episode cards that say where the lag happened and how confident the classification is, and a big Lag happened button. A phone-sized page lives at /phone.

When you stop (or every 30 seconds while it runs) Lag Lens writes report.html: a single file with the charts, every episode, the XB7 DOCSIS readings, and a plain-English "Tell Comcast" block you can paste into a support chat or hand to a technician.

Troubleshooting

macOS: "gateway unreachable" or everything local fails

macOS blocks local-network access per app. Allow it for your terminal app: System Settings → Privacy & Security → Local Network, then switch on Terminal (or iTerm, Ghostty, WezTerm, Visual Studio Code, whichever you launched it from). Restart Lag Lens afterwards. The doctor detects this case and tells you which app to allow.

Bazzite / Steam Deck style Linux
  • Switch to Desktop Mode, open Konsole, and run it from ~/lag-lens (your home folder is writable and persists across updates; the system image is not).
  • If your phone cannot reach the dashboard, the firewall zone probably blocks port 8787. Either run sudo firewall-cmd --add-port=8787/tcp for this session, or open the port in the zone your Ethernet interface is in. Lag Lens itself never needs root.
  • Keep the screen from sleeping while you monitor; Lag Lens asks the system to inhibit sleep, but a lid close still stops the network.
My phone can't open the dashboard
  1. Phone and computer are on the same Wi-Fi / same network (not cellular, not a guest network, no VPN on either side).
  2. You typed http://, not https://. Browsers upgrade to https silently; Lag Lens serves plain http on your LAN only.
  3. The port is 8787 (or the next free one; the terminal prints the exact URL). Try the IP address the terminal shows rather than a hostname.
  4. Scan the QR code in the terminal or on the dashboard instead of typing the address.
  5. On Linux, check the firewall (see the Bazzite note above). On macOS, if a third-party firewall is installed, allow incoming connections for python3.
It says python3 is too old or missing

Lag Lens needs Python 3.9 or newer. On macOS, xcode-select --install provides it. If you installed a newer Python with Homebrew, start.sh prefers it automatically; you can force one with LAGLENS_PYTHON=/path/to/python3 bash start.sh.

Privacy

Nothing phones home. The only traffic Lag Lens generates is the probes it is there to measure: ICMP and TCP to your gateway, the Comcast hops on your path, Cloudflare and Google anycast addresses, Xbox Live sign-in hosts, NTP, and small CDN fetches. There is no telemetry, no account, and no update is ever installed without you running bash start.sh --update.

If you let it read your XB7's DOCSIS stats, the gateway password stays in config.json on your machine (file mode 600) and is only ever sent to the gateway itself. It is redacted from logs, the dashboard and the report. Reports and exports are files on your disk; you decide who sees them.

What's new in 1.0.21

[1.0.21] - 2026-10-18

Changed

  • The modem is named by its model instead of always "XB7": the hardware page's model is read (`CGM4981COM` → XB8, `TG4482A`/`CGM4331COM` → XB7, `TG3482G`/`CGM4140COM` → XB6, anything else by its own name) and used in the dashboard's modem panel, verdicts, evidence lines, modem messages and the Tell-Comcast header ("Modem: XB8 (CGM4981COM) in bridge mode"). Until a status page has been read the old "XB7" wording stays; texts that cannot know the model say "gateway" or "modem".

Fixed

  • A dashboard or phone page left open while Lag Lens restarted kept the old session's token: it showed UNREACHABLE during the restart and then looked connected while every press was refused. Pages now reload themselves when they see a new session.
  • A test of the single-instance guard could check a freshly started fake monitor before it showed its own command line (intermittent on a busy machine); it now waits for it.