Linewatch

Internet quality over time — agent-native. A simplified speedtest.net that doesn't stop at one number: it keeps measuring, charts the trend, records dropouts, and hands the evidence to you (or your AI agent) as clean JSON.

Built 19 Aug 2026. Working label — naming can go through the usual round later.

Why it exists

A point-in-time speed test can look fine while the line is actually flapping or sagging every evening. Three failure modes need three kinds of measurement:

Failure mode	What catches it
Throughput sag (paying for 300, getting 60)	scheduled speed tests
Flapping (start-stop-start dropouts)	cheap latency probes every 45 s
Latency/bufferbloat (speed fine, calls stutter)	latency + jitter per measurement

Design principle: heavy tests sparsely, cheap tests densely.

No servers of our own: measurement runs against Cloudflare's public, CORS-open speed endpoints (speed.cloudflare.com), so the engine works from any browser or Node process for free.

Layout

packages/core   isomorphic measurement engine + stats + types (browser & Node)
packages/cli    `linewatch` CLI — every command speaks --json; JSONL store in ~/.linewatch/
packages/mcp    MCP server (stdio) — agents run tests & read history, zero login
apps/web        PWA — GO button + live gauge, Monitor mode, history charts, CSV export

Quickstart

npm install
npm run build

# human: web app
npm run dev                      # → http://localhost:5173  (installable as a PWA)

# human or agent: CLI
node packages/cli/dist/index.js test            # one speed test
node packages/cli/dist/index.js monitor         # test every 15m + probe every 45s
node packages/cli/dist/index.js summary --since 7d --json

# agent: MCP (Claude Code)
claude mcp add -s user linewatch -- node $(pwd)/packages/mcp/dist/index.js

MCP tools: run_speed_test, run_latency_probe, get_history, get_summary, get_store_info.

Agent-native principles

1. No interactive auth for machines. CLI and MCP hit the same local JSONL store (~/.linewatch/results.jsonl) — append-only, greppable, parseable.
2. JSON is the first-class output; the human UI is a rendering of the same rows.
3. Cheap primitives for autonomous use: an agent that suspects network trouble calls run_latency_probe (<2 s, ~zero data) and only escalates to run_speed_test (~20 s, ~100–500 MB) when needed — the tool descriptions state those costs so agents can decide.

Data notes

• A speed test transfers data at full line rate for ~18 s: roughly line_Mbps × 18 / 8 MB per test. Monitor mode at 15 min on a 100 Mbps line ≈ 20+ GB/day — fine on unlimited fibre, choose a slower cadence on capped plans.
• Web results live in the browser's IndexedDB; CLI/MCP results in ~/.linewatch/. They merge in Phase B (cloud sync).

See ROADMAP.md for where this goes (cloud sync, alerts, tray app, mobile, product).