A TypeScript library for building Home Assistant automations and custom integrations. Connects via WebSocket and MQTT.
bun add github:visualglitch91/hass-sidekickimport { createSidekick } from "hass-sidekick";
const sk = createSidekick({
namespace: "my-app",
hass: {
host: "http://homeassistant.local:8123",
token: "your-long-lived-access-token",
},
mqtt: {
url: "mqtt://homeassistant.local:1883",
authentication: { username: "mqtt-user", password: "mqtt-pass" }, // optional
},
server: {
hostname: "0.0.0.0",
port: 3000,
authorize: (req) => req.headers["authorization"] === "Bearer my-secret", // optional
},
});
await sk.init();createSidekick returns a sidekick instance synchronously. Call init() to connect to Home Assistant -- it waits for HA to be running before resolving. Once resolved, you can use sk to read state, call services, create devices, track changes, and register webhooks.
| Property | Purpose |
|---|---|
sk.state(id) |
Read entity state |
sk.service(domain.service, payload) |
Call HA service |
sk.turnOn(id) / sk.turnOff(id) |
Convenience shortcuts |
sk.track.* |
React to state/attr/event changes |
sk.automation(name) |
Build declarative automation pipelines |
sk.log |
Pino logger for structured logging |
sk.device(config) |
Create MQTT entities grouped under a device |
sk.server.* |
Register webhooks, RPC methods, and HTTP routes |
sk.connection.* |
Monitor connection status |
sk.dispose() |
Clean up everything |
import { createSidekick, minutes } from "hass-sidekick";
const sk = createSidekick({ /* config */ });
await sk.init();
// Turn off lights when nobody's home
sk.track.stateTo("group.family", "not_home", () => {
sk.service("light.turn_off", { entity_id: "all" });
});
// Create a custom sensor
const weather = sk.device({ id: "weather", name: "Weather Station" });
weather.sensor({
uniqueId: "feels_like",
name: "Feels Like",
getValue: () => fetchFeelsLike(),
unitOfMeasurement: "°C",
deviceClass: "temperature",
});