# 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

```sh
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).