README
¶
roamr
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
| Command | Does |
|---|---|
roamr |
recommend the best known network here (default) |
roamr current |
diagnose the network you're on (incl. latency/jitter) |
roamr list |
list known networks and their scores |
roamr watch |
sample continuously; suggest a switch only when one is durably better |
roamr speedtest |
measure real download throughput of the network you're on |
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.
Menu-bar app (macOS)
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
| OS | Provider | Status |
|---|---|---|
| macOS | signed CoreWLAN helper via macwifi (ADR-0002) |
working (Apple Silicon, macOS 13+) |
| Windows | native WLAN API (wlanapi.dll, ADR-0004) |
working (verified on device; requires Location enabled) |
| Linux | nmcli (NetworkManager) |
implemented (fixture-tested; pending on-device check) |
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.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
roamr
command
Command roamr recommends the best WiFi network for your current location.
|
Command roamr recommends the best WiFi network for your current location. |
|
internal
|
|
|
cli
Package cli wires command-line input to the engine.
|
Package cli wires command-line input to the engine. |
|
render
Package render turns a Recommendation into user-facing output.
|
Package render turns a Recommendation into user-facing output. |
|
pkg
|
|
|
engine
Package engine is roamr's OS-agnostic orchestrator.
|
Package engine is roamr's OS-agnostic orchestrator. |
|
model
Package model holds the cross-platform data types that flow through roamr.
|
Package model holds the cross-platform data types that flow through roamr. |
|
provider
Package provider defines the single seam between roamr's OS-agnostic core and platform-specific WiFi access.
|
Package provider defines the single seam between roamr's OS-agnostic core and platform-specific WiFi access. |
|
provider/internal/sys
Package sys is the one place, besides the providers themselves, that runs OS commands.
|
Package sys is the one place, besides the providers themselves, that runs OS commands. |
|
provider/linux
Package linux implements the NetworkProvider for Linux via NetworkManager's nmcli.
|
Package linux implements the NetworkProvider for Linux via NetworkManager's nmcli. |
|
provider/mock
Package mock is a deterministic, no-hardware provider used for tests, CI (which has no wireless card) and `roamr --demo`.
|
Package mock is a deterministic, no-hardware provider used for tests, CI (which has no wireless card) and `roamr --demo`. |
|
provider/windows
Package windows implements the NetworkProvider for Windows via the native WLAN API (wlanapi.dll), reached through the standard-library syscall package (no cgo).
|
Package windows implements the NetworkProvider for Windows via the native WLAN API (wlanapi.dll), reached through the standard-library syscall package (no cgo). |
|
score
Package score turns a Network's observable properties into a 0–100 quality estimate plus human-readable reasons (the "why").
|
Package score turns a Network's observable properties into a 0–100 quality estimate plus human-readable reasons (the "why"). |
|
speedtest
Package speedtest measures real download throughput of the active internet connection.
|
Package speedtest measures real download throughput of the active internet connection. |