ZeroHome

A Home Assistant custom integration that bridges a ZeroClaw agent into HA: a live chat card, a memory log, a cron-job schedule view, telemetry sensors, and a full Assist conversation agent — all talking to your own ZeroClaw gateway.

Why a backend integration, not just a card

A ZeroClaw gateway binds to 127.0.0.1 by default and every route requires a bearer token. A browser loading your Home Assistant dashboard can be on a different machine entirely, so a pure client-side Lovelace card can't reach it directly. This integration ships a small Python component (custom_components/zeroclaw_bridge/) that runs on the same host as Home Assistant and proxies requests server-side — the gateway token lives only in the HA config entry, never in the browser or in any card's YAML config.

browser --(HA's own auth)--> HA: GET /api/zeroclaw_bridge/...
                                    |
                                    v (server-side, token attached, never sent to the browser)
                             ZeroClaw gateway: GET /api/...

Features

• Chat card — live message history for a ZeroClaw session, with readable tool-call/ tool-result formatting, a live in-turn tool-call trace (⏳ running / ✅ success / ❌ failed), a "thinking" indicator, and a clear-chat button.
• Memory log card — read-only, recency-sorted view of everything ZeroClaw has stored in memory, with category badges.
• Cron jobs card — read-only, soonest-next-run-first list of ZeroClaw's scheduled tasks, with enabled/paused state and last-run status.
• Telemetry sensors — connection status, last tool call (name/status/duration), daily/ monthly cost, memory count, skill count, cron job count — all sharing one device so they group together in HA's entity list instead of showing up as unrelated rows.
• Assist conversation agent — registers as a selectable conversation agent under Settings → Voice assistants, so ZeroClaw is reachable via any Assist pipeline (voice satellites, wake-word, the Assist chat box), not just its own channels.

Requirements

• A running ZeroClaw gateway (zeroclaw daemon or zeroclaw gateway start), reachable from the Home Assistant host.
• A paired device token — see ZeroClaw's pairing docs (its own web dashboard, or zeroclaw gateway get-paircode --new + a POST /pair call from the gateway's host).
• At least one configured agent alias (a [agents.<alias>] entry in the gateway's config.toml) — you'll enter this alias during setup.

Install

Via HACS

1. In HACS, add this repository as a custom repository (category: Integration), or install it directly if it's been added to the HACS default list.
2. Restart Home Assistant.
3. Settings → Devices & Services → Add Integration → ZeroHome / ZeroClaw Bridge.

Manual

1. Copy custom_components/zeroclaw_bridge/ into <config>/custom_components/ on your Home Assistant host.
2. Restart Home Assistant.
3. Settings → Devices & Services → Add Integration → ZeroHome / ZeroClaw Bridge.

Configuration

The config flow asks for:

Field	Description
Host	The ZeroClaw gateway's address (127.0.0.1 if it runs on the same host as HA)
Port	The gateway's port (default 42617)
Gateway token	A paired device token
Agent alias	The [agents.<alias>] name to talk to — required, ZeroClaw has no default agent
Default session ID	Which session the chat/memory cards read from by default

Only one ZeroClaw gateway is supported per Home Assistant instance today (see Known limitations). A Reconfigure flow lets you update host/port/token/agent alias in place if the gateway moves (e.g. a DHCP lease change) without deleting and re-adding the integration. A Reauth flow triggers automatically if the gateway rejects the configured token (rotated or revoked).

Adding the cards to a dashboard

type: custom:zeroclaw-chat-card
session_id: default
title: ZeroClaw

type: custom:zeroclaw-memory-card
title: ZeroClaw Memory

type: custom:zeroclaw-cron-card
title: ZeroClaw Cron

Cards register themselves as Lovelace resources automatically on integration setup — no manual resource-URL step needed. session_id on the chat card matches whichever ZeroClaw session you want to view; each channel/peer gets its own session (see ZeroClaw's own session docs), so a fresh integration setup showing an empty chat card against the default session ID is expected, not a bug — point it at the session key you actually want to watch.

Architecture notes

• Polling, not push. Sensors poll every 20s; the chat card's messages/thinking-indicator poll every 5s. No persistent SSE/WebSocket listener yet — good enough to view history and status, not ideal for instant telemetry.
• All frontend cards are plain HTMLElements, no build step. They're served straight from the integration's frontend/ folder with zero bundling, and share lifecycle/error/fetch-guard boilerplate via frontend/zeroclaw-card-base.js.
• The conversation agent relays over ZeroClaw's /ws/chat WebSocket (its only interactive chat surface — no OpenAI-style REST endpoint exists) rather than using Home Assistant's own chat_log/LLM-tool-use machinery, since ZeroClaw owns conversation memory itself.

See docs/gateway-api-notes.md for a source-grounded audit of which ZeroClaw gateway API capabilities this integration relies on (and which are still gaps worth filing upstream), and docs/baseline-review.md for a past multi-agent code review and its fix pass.

Known limitations

• Single ZeroClaw gateway per Home Assistant instance — multi-gateway support (per-entry routing) is real future work, not yet built.
• unique_id is host:port, not a stable gateway identifier (ZeroClaw's /api/health doesn't expose one) — mitigated with a reconfigure flow rather than solved outright.
• No message sending from the chat card itself — it's a read-only history view (+ clear). The conversation agent can send, via a separate path (Assist → /ws/chat).
• The /ws/chat timeout (90s) doesn't abort the in-flight ZeroClaw turn server-side on expiry.
• Cron/config-editing (add, remove, pause, resume) isn't exposed from the cards — v1 scope is read-only visibility; use ZeroClaw's own CLI/gateway API for mutation.

Changelog

• v0.1 — Chat history card (read-only), backed by a proxy view for GET /api/sessions/{id}/messages.
• v0.2 — Readable tool-call/tool-result formatting, a clear-chat button, connection + last-tool-call sensors.
• v0.3 — Full Assist conversation agent (/ws/chat relay), cost-tracking sensors, a "thinking" indicator.
• v0.4 — Memory-count and skill-count sensors.
• v0.5 — Memory log card; fixed a horizontal-scroll rendering bug shared across cards.
• v0.6 — A 12-finding multi-agent code review fix pass: real device grouping (one shared DeviceInfo, localized entity names), a reauth flow for rotated tokens, coordinator failures now surface as real HA failures instead of being silently swallowed, single-instance enforcement, shared client.py/zeroclaw-card-base.js extraction to kill duplication, and a fixed crash on a null event timestamp.
• v0.7 — Cron jobs card + cron_job_count sensor (backed by ZeroClaw's GET /api/cron); a live in-turn tool-call trace on the chat card (replacing the old plain "thinking" spinner), built from the same tool_call_start/tool_call SSE events already powering the last-tool sensor.
• v0.8 — The ZeroClaw agent alias is now a config-flow field (agent_alias) instead of a hardcoded constant, so this integration works against any ZeroClaw agent name, not just one specific deployment's. First public release.

Contributing

Issues and PRs welcome. If you hit a real ZeroClaw gateway API gap while extending this integration, check docs/gateway-api-notes.md first — several gaps are already tracked there with upstream issue links.

License

MIT — see LICENSE.