Find the best WiFi network for where you are, without dropping your connection.

In an office (or home) with several WiFi networks, the best one changes as you move, and "best" isn't just signal bars. A network can show full bars and still be slow: crowded 2.4 GHz, an old WiFi standard, a congested channel. roamr reads what your OS already knows about every nearby saved network, scores them for real-world quality, explains why, and tells you which to use.

Status: live on macOS (brew install --cask sourabh-khot65/tap/roamr), plus a companion menu-bar app. Windows is verified working; Linux is implemented and in preview (see Platforms). No Mac? Try roamr --demo.

Install

macOS (recommended). Install with Homebrew. The cask strips the quarantine attribute on install, so the binary runs without the Gatekeeper warning a browser download would trigger:

brew install --cask sourabh-khot65/tap/roamr

Windows. Install with Scoop:

scoop bucket add roamr https://github.com/sourabh-khot65/scoop-bucket
scoop install roamr

Any platform. Download a binary from the latest release, or build from source with Go 1.26+:

go install github.com/sourabh-khot65/roamr/cmd/roamr@latest

Binaries from the Releases page (as opposed to Homebrew) are unsigned, so Gatekeeper quarantines them on macOS. Clear it once with xattr -d com.apple.quarantine ./roamr. Homebrew installs aren't affected. Notarizing roamr's own binary is planned but out of scope for v0.x.

Quick start

Once installed, try the built-in demo (no WiFi hardware needed):

roamr --demo --why          # or, from source: go run ./cmd/roamr --demo --why

→ Switch to Office-6E — clearly better here.

  Office-6E             ▀▀▀▀▁  86%  6GHz   ax    score  95
      - 6 GHz — fast, uncongested
      - channel is clear
  Office-5G             ▀▀▀▀▀  92%  5GHz   ax    score  93
      - strong signal (-54 dBm)
      - channel is clear
  Office-Guest          ▀▀▀▁▁  68%  5GHz   ac    score  81
      - channel is clear
▸ Office-2G             ▀▀▀▀▀ 100%  2.4GHz n     score  69
      - strong signal (-47 dBm)
      - 2.4 GHz — slower, more interference
      - WiFi 4 — older, slower standard

You're on Office-2G (the ▸) with 100% signal, but roamr ranks it last, 2.4 GHz on old WiFi 4, and points you to Office-6E instead. That gap between "full bars" and "actually good" is the whole point of roamr.

Commands

Flags: --why (explain scores), --json (machine-readable), --demo (no hardware), --interval / --samples (for watch).

roamr is advisory: it reads what your OS knows and never changes your connection. It tells you which saved network is best; you switch from your OS's Wi-Fi menu.

watch smooths each network's score over time (EMA) and only flags a switch when a challenger beats your current network by a clear margin for several consecutive samples, so the recommendation doesn't flap on signal noise or 2.4/5 GHz band-steering.

How it works

Scoring is passive and never disconnects you. It weighs signal, band, channel congestion, WiFi standard, and (for the network you're on) live latency. The details are in docs/architecture.md; platform support sits behind one pluggable seam, described in docs/adding-a-platform.md.

A companion menu-bar app shows the live ranked list and the "why" as a dropdown — quality-coloured scores, signal bars, and an amber cue when a network is durably better. It reads roamr watch --json, so all the scoring stays in the CLI; like the CLI, it only advises and never switches for you.

make app          # build macos/Roamr.app (Swift, no Xcode needed)
make install-app  # build and install it to /Applications

Platforms

macOS needs Location permission to read WiFi details (granted to the embedded helper on first run); no paid Apple account is required to build or run roamr (see ADR-0002). The macwifi dependency requires Go 1.26+ and targets Apple Silicon; macOS does not report PHY mode, so that scoring signal is skipped there.

Development

go build ./...   # build everything
go test ./...    # run tests (no WiFi hardware needed)
go vet ./...

License

MIT. See LICENSE.