boxel: Skill for Claude Code

Client performance diagnosis

The host runs an always-on, passive client performance instrument. It samples the main thread and hooks the client's own server interactions, batches what it sees into a bounded ring buffer, and beacons the batch to the realm-server's POST /_client-telemetry route. The route re-emits one structured JSON log line per event on the boxel:client-perf channel; alloy tails the realm-server's stdout into Loki, and the "Host App Client Performance" Grafana dashboard (uid boxel-client-perf) — the host app is the instrumented client; boxel-cli and other API clients do not beacon — reads those lines with | json.

This is the tool for turning a vague field complaint — "the app was slow loading my card", "my tab froze" — into a measured story attributed to a specific account. Every event carries the authenticated matrix_user_id and a per-tab session_id, so you can start from who and reconstruct what their browser was doing.

The pipeline

host instrument  →  fetch(keepalive) POST /_client-telemetry  →  one `boxel:client-perf`
JSON log line per event  →  alloy tails realm-server stdout  →  Loki  →  Grafana `| json`

Nothing about this is a separate data store: it rides the same log pipeline every realm-server log already uses. A client event is just a realm-server log line with a known shape.

What gets measured, and how often

The instrument gathers at each signal's natural cadence, decoupled from how often it talks to the network:

• The main thread is probed by a ~100ms heartbeat; long-animation-frame (LoAF) / longtask observers fire as the browser reports them; the JS self-profiler (on sampled sessions) samples continuously; the event hooks (card-load, server-request, deserialize, rebuild, realm-event) record at the instant each occurs; uncaught exceptions and unhandled rejections are captured as they surface, coalesced by signature so a loop reports a count rather than a flood.
• Those samples accumulate in a ring buffer that a separate ~1s flush loop batches and POSTs at most once per second, and only when the batch carries signal. An otherwise-quiet tab still beacons a compact keepalive on a fixed cadence, so an active session_id is visible even when nothing is wrong.