HA-Websocket-Stripper: Instructions file for Claude Code

HA WebSocket Stripper — project context

What this is / why it exists

Home Assistant Lovelace dashboards on a large instance (here ~3,600 entities) load slowly because, at startup, the frontend pulls every entity over the websocket (get_states + a full subscribe_entities) plus the entity/device/area registries, on top of the frontend JS bundles and every HACS custom-card module.

For wall-panel / kiosk dashboards (a fridge screen, etc.) that only show a handful of entities, that firehose is pure waste. This project makes those dashboards load fast without changing how they look, by serving the real HA frontend through a reverse proxy that trims the entity websocket to just the entities each dashboard uses.

Why this approach (history — don't re-litigate)

We first tried a lighter path: a long-poll backend + a hand-written approximated renderer that redrew cards in plain HTML. It loaded fast but the owner wants pixel-perfect fidelity, and re-implementing Mushroom/button-card/clock-weather/etc. is a losing battle. So we pivoted to: run HA's real frontend, just strip the websocket. That approximation approach was abandoned; this repo is the chosen direction.

A pure "reuse only the card-rendering JS" idea isn't viable: HA's core cards live inside the compiled frontend bundle and can't be loaded standalone. The realistic way to get the real cards + a trimmed subscription is this reverse proxy.

Mechanism

HTTP: everything proxies straight to HA untouched (frontend bundles, /auth/*, registries, lovelace/config, /hacsfiles/*, camera proxy, …).

WebSocket (/api/websocket): the proxy terminates the browser socket, opens its own socket to HA, and relays both ways, modifying only:

• subscribe_entities with no filter → inject entity_ids = <allowlist> so HA streams only those entities (trims at the source);
• the get_states result → filtered to the allowlist.

Everything else (auth handshake, registry calls, config, events) passes through, so the real frontend renders your real cards — just without the all-entities firehose. The browser relays its own user token in the ws auth; the proxy doesn't touch auth.