Docs

Last updated July 19, 2026

Quick start

The recommended path is browser system wiring. The optional command installs the verified connector, registers autostart, starts it on 127.0.0.1:41414, and opens the local dashboard.

The API — try it yourself

The local connector serves three GET endpoints on loopback. With it running, these work from any terminal on your machine, and only there:

{"status":"ready","engineVersion":"20.0.17","pna":true}

Detected agents with the date range of their logs, last scan time, and any scan error (with the exact fix command).

Normalized aggregates: per-day rows with per-agent children and per-model breakdowns — token counts, model IDs, timestamps, API-equivalent cost. shape=monthly|session for the other views. Add &fresh=1 to force a rescan — throttled to one per 5 seconds; a throttled response serves cache and says so with "throttled": true. Rescans otherwise run every 60 s, single-flight (concurrent callers share one engine run).

Security model, verifiable

• Binds 127.0.0.1 only. Unreachable from your network — try it from another machine.
• Host validation: requests must carry Host: 127.0.0.1:41414 (or localhost) — this is the DNS-rebinding defence. curl -H "Host: evil.com" …/health → 403.
• Origin allowlist: browser pages may read it only from this site's exact origin. Local pages are refused unless local development mode is enabled. curl -H "Origin: https://evil.com" …/usage → 403.
• PNA: Chrome's private-network preflight is answered (Access-Control-Allow-Private-Network, echoed only when requested); /health advertises pna:true.
• GET-only and local-only by default. The update command fetches signed release metadata only when invoked. Explicit account pairing enables allowlisted aggregate sync; deleting sync.json disables it.
• Never read: message.content. The parser whitelists usage fields; prompts and responses don't exist in its output.

Where your numbers come from

1. If a log records costUSD, the local connector trusts that number verbatim.
2. Otherwise, known models are computed with its pinned pricing table.
3. Models that postdate that table keep the engine's number but are marked ~ estimated.
4. Raw values are summed before display; USD is then rounded once to two decimals using half-even rounding.
5. The machine running the local connector owns the timezone and calendar-day boundaries.

CLI reference

• Base command: node ~/.usage-radar-connector/bin/usage-radar-connector.cjs
• … start — run in the foreground (logs to stdout)
• … restart — stop whatever is running, re-register autostart, start this build detached
• … stop — stop; beats launchd/systemd keep-alive
• … status — autostart + running state + versions
• … selftest — prove the engine runs on this machine (prints tokens visible)
• … repair — reinstall the per-platform engine binary (fixes npm installs that skipped optional deps)
• … update — check + self-update, checksum-verified; --check looks only. The CLI's only network call, ever.
• … uninstall — removes autostart and the local connector completely; never touches your agent logs
• … --version

The port defaults to 41414. Local-development and headless modes are also supported.

Where your data lives

• Local connector: its private app-data folder contains the code, one dependency, and a per-install 32-byte secret (0600) that pseudonymises session labels. Uninstall and it's gone.
• This site: your browser's IndexedDB (events, provider reports, cached pricing) and localStorage (preferences). Nothing server-side unless you explicitly sign in and enable sync — and then aggregates only, schema-enforced.

Zero-install paths

• Folder read (Chrome/Edge/Brave): on Connect system logs, point the tab at ~/.claude/projects — deterministic parsers run in a Web Worker in the page. Exact numbers, nothing installed.
• Provider keys: Anthropic / OpenAI / OpenRouter billing truth, keys kept in your browser.
• Estimator: arithmetic on published rates, labelled as an estimate.

Verify what you run

SHA-256 checksums for connector artifacts are published at /downloads/checksums.json; the version manifest lives in the version manifest. Source: github.com/abhijay-sudo/usage-radar. The repository's connector suite runs 24 tests, including the global golden, origin/host rejections, staged updater, and single-flight throttle.

Uninstall

Removes everything, touches nothing else, and never changes your agent logs.