Smart home integration β summon your house into a living agent.
CI License Phase 2 Core Discord
Status: Phase 2 β On Hold. Home Assistant integration is implemented with REST API, WebSocket, device discovery, skill tools, and SOUL.md generation. Per the design research, smart home integration is deprioritized to Phase 2. Phase 1 focuses on chat-native family hub (Telegram/WeChat/Web).
casa is the smart home integration layer for OpenOctopus. It bridges your Home Realm with Home Assistant, turning your house and its devices into summoned entities with memory and proactive behavior.
Casa means "home" in Spanish and Italian β a warm word for a warm integration.
pnpm add @openoctopus/casa
Create a .env file (or set environment variables):
HA_URL=http://homeassistant.local:8123 HA_TOKEN=your_long_lived_access_token_here
Or configure programmatically:
import { loadCasaConfig, createCasaSkill } from '@openoctopus/casa' const config = loadCasaConfig({ haUrl: 'http://homeassistant.local:8123', haToken: 'your-token', autoDiscover: true, pollInterval: 30, domains: ['light', 'switch', 'climate', 'lock'], }) const skill = createCasaSkill(config)
import { loadCasaConfig, createCasaSkill } from '@openoctopus/casa' const config = loadCasaConfig() const skill = createCasaSkill(config) // skill.tools contains: casa_get_state, casa_set_state, // casa_list_devices, casa_get_history, casa_trigger_scene
import { HaClient, discoverDevices } from '@openoctopus/casa' const client = new HaClient('http://ha.local:8123', 'token') const devices = await discoverDevices(client, ['light', 'climate'])
import { generateDeviceSoul } from '@openoctopus/casa' const soul = generateDeviceSoul(device) // Returns a full SOUL.md with personality, behaviors, and memory notes
import { HaWsClient } from '@openoctopus/casa' const ws = new HaWsClient('http://ha.local:8123', 'token') await ws.connect() await ws.subscribeEvents((event) => { console.log(`${event.data.entity_id} changed`) })
| Domain | Description | Personality |
|---|---|---|
light |
Lights and dimmers | Warm, friendly, mood-aware |
switch |
On/off switches | Reliable, straightforward |
climate |
Thermostats and HVAC | Precise, comfort-focused |
lock |
Smart locks | Vigilant, security-conscious |
cover |
Blinds and shutters | Measured, privacy-aware |
fan |
Fans and ventilation | Breezy, easygoing |
media_player |
Media devices | Entertaining, expressive |
sensor |
Sensors (temperature, etc.) | Observant, data-driven |
binary_sensor |
On/off sensors (motion, door) | Attentive, clear-cut |
See the souls/ directory for example personality files:
souls/thermostat.soul.mdβ A precise, comfort-focused thermostatsouls/smart-lock.soul.mdβ A vigilant, security-conscious lock
casa/
βββ src/
β βββ index.ts # Public API
β βββ config.ts # Zod config schema
β βββ types.ts # Device types, skill types
β βββ ha/
β β βββ client.ts # HA REST API client
β β βββ ws-client.ts # HA WebSocket client
β β βββ types.ts # HA state/service/event types
β βββ discovery/
β β βββ device-discovery.ts # Scan HA devices
β β βββ entity-mapper.ts # HA entity to OpenOctopus mapping
β βββ skill/
β β βββ casa-skill.ts # SkillDefinition factory
β β βββ tools/ # Individual tool implementations
β βββ soul/
β βββ device-soul-generator.ts # SOUL.md generation
βββ souls/ # Example SOUL.md files
pnpm install pnpm build # Build with tsdown pnpm test # Run tests with vitest pnpm test:watch # Watch mode pnpm typecheck # TypeScript check pnpm lint # oxlint
| Project | Description |
|---|---|
| openoctopus | Core monorepo |
| coral | Cross-realm workflow engine |
| realms | Official realm packages |
Join The Reef (Discord) to discuss smart home integration ideas, or open an issue with use cases.
See CONTRIBUTING.md for general guidelines.