# yslow

A command-line tool that diagnoses why your network connection is slow (or feels slow).

Instead of just reporting numbers, yslow isolates *where* the problem is — your local network (wifi/router), your ISP, or the broader internet — and tells you in plain language.


```
╻ ╻┏━┓╻  ┏━┓╻ ╻┏━┓
┗┳┛┗━┓┃  ┃ ┃┃╻┃ ╺┛
 ╹ ┗━┛┗━╸┗━┛┗┻┛ ╹

Is it slow?
● YES!

Why?
  ⚠ network no targets reachable (internet may be down) (1x, ongoing)
  ⚠ LAN     gateway unreachable (unusual routing setup) (1x, ongoing)
  ⚠ WiFi    very weak signal (too far from access point) (1x, ongoing)

Details
  WiFi:         -82 dBm (2.4 GHz), 6 Mbps TX, 6 Mbps RX
  LAN:          gateway 192.168.1.1 unreachable
  ISP/internet: all targets unreachable
  10.0.0.1:       3.0 ms cached,  45.0 ms uncached ✱
  Google DNS:    25.0 ms cached,  60.0 ms uncached
  OpenDNS:       35.0 ms cached,  42.0 ms uncached
  Cloudflare DNS:  9.0 ms cached,  40.0 ms uncached
```

## What it checks

- **Gateway latency** — how fast your machine can talk to your router. High latency or jitter here points to wifi congestion, a bad cable, or an overloaded router.
- **Internet latency** — TCP handshake time to multiple well-known servers (Cloudflare, Google, OpenDNS).
- **DNS resolution** — cached and uncached lookup times for your configured resolver and public resolvers (Google, Cloudflare, OpenDNS). Flags slow resolvers and compares your configured resolver against public alternatives.
- **Packet loss** — at both the local and internet level.
- **Jitter** — variance in latency, which causes buffering, choppy calls, and inconsistent page loads.
- **Wifi Signal Strength** — how strong your wifi signal is.

## Usage

```
uvx yslow              # one-shot check
uvx yslow -w           # continuous monitoring (every 30s)
```

Requires Python 3.10+. Works on Linux and macOS.

## How it works

See `docs/`

## Development

```
uv sync                  # install deps
./check.sh               # run all checks (format, lint, typecheck, tests)
uv run ruff check --fix  # lint
uv run ruff format       # format
```

## Documentation

See [`docs/metrics.md`](docs/metrics.md) for details on what yslow measures (RTT, packet loss, jitter, DNS), how each metric is calculated, and the thresholds used for diagnosis.

## Planned

See `TODO.md`
