Cómo Usar Claude Code en Home Assistant: Guía Completa de Integración IA
TL;DR - Resumen Rápido
- Add-on gratuito que integra Claude Code CLI de Anthropic en Home Assistant
- Automatiza con lenguaje natural: "Si salgo de casa, apaga todo excepto la nevera"
- Crea scripts YAML sin saber programar - Claude los genera por ti
- Persistencia de configuración - sobrevive a reinicios
- Código disponible: GitHub
¿Por Qué Integrar Claude Code en Home Assistant?
La automatización del hogar ha dado saltos agigantados en los últimos años, pero la integración real de Inteligencia Artificial (IA) sigue siendo un reto para muchos usuarios avanzados y desarrolladores. Home Assistant es una plataforma fantástica para gestionar dispositivos y rutinas, pero ¿qué pasa cuando queremos que la IA nos ayude a automatizar, analizar o extender nuestras capacidades, sin limitarnos a los asistentes tradicionales?
En este artículo quiero compartir el proceso de diseño, desarrollo y despliegue de claude-code-ha, un complemento avanzado para Home Assistant que trae la potencia del CLI de Claude Code (Anthropic) directamente a tu entorno domótico, permitiendo tareas inteligentes, análisis y automatizaciones personalizadas. Te contaré por qué era relevante, cómo abordé el problema, los retos técnicos, la arquitectura elegida, y los aprendizajes.
¿Por qué integrar Claude Code en Home Assistant?
Home Assistant es líder en automatización doméstica, pero su capacidad de razonamiento y scripting avanzado depende en gran parte de la habilidad del usuario con YAML, Python o Node-RED. Por otro lado, soluciones de IA como Claude Code de Anthropic han demostrado capacidades impresionantes en procesamiento de texto, análisis de datos y generación de código. Sin embargo, integrar ambos mundos no es trivial:
- Hay que asegurar persistencia en las configuraciones y paquetes, ya que los addons suelen ser efímeros.
- Se requiere una interfaz amigable para que el usuario pueda interactuar con la IA dentro del mismo entorno Home Assistant.
- La gestión de credenciales y la seguridad cobra especial relevancia al tratarse de comandos automatizados y potencialmente sensibles.
La motivación principal fue: ¿cómo puedo dotar a Home Assistant de una capa de IA conversacional y de automatización avanzada, permitiendo a los usuarios delegar tareas complejas a un modelo como Claude, pero manteniendo la robustez y flexibilidad del entorno?
Arquitectura y decisiones técnicas
Overview de la arquitectura
El complemento claude-code-ha se diseñó como un Add-on de Home Assistant, encapsulado y portable, que integra varias tecnologías para orquestar la interacción entre el usuario, Claude Code y el propio Home Assistant:
1+----------------------------+2| Home Assistant Add-on |3| (Docker Container) |4| |5| +----------------------+ |6| | Claude Code CLI | |7| | (Node.js) | |8| +----------------------+ |9| |10| +----------------------+ |11| | Python Scripts | |12| +----------------------+ |13| |14| +----------------------+ |15| | Shell Wrappers | |16| +----------------------+ |17| |18| +----------------------+ |19| | HTML/JS Frontend | |20| +----------------------+ |21+----------------------------+Principales componentes
- Shell Scripts: Orquestan el arranque, instalación de dependencias, configuración persistente y ejecución de los distintos servicios.
- Python Utilities: Permiten manipulación avanzada de archivos, integración con APIs, y procesamiento de datos que complementan las limitaciones del entorno Shell.
- Claude Code CLI: El núcleo de IA, basado en Node.js, gestionado desde el contenedor del addon.
- Frontend HTML/JS: Pequeña interfaz para interacción directa, soporte de subida/análisis de imágenes y feedback al usuario.
- Dockerfile & Nix: Garantizan portabilidad y reproducibilidad, gestionando la instalación de dependencias y el entorno exacto que requiere el complemento.
Decisiones clave de diseño
- Persistencia de paquetes (Python, sistema): Los Add-ons de Home Assistant suelen ser efímeros, perdiendo paquetes tras reinicios. Resolví esto con un sistema de almacenamiento y reinstalación automática usando un archivo de configuración y scripts de arranque.
- Integración CLI de Claude Code: Decidí invocar la CLI de Claude Code directamente desde el contenedor, lo que provee máxima flexibilidad y permite aprovechar futuras mejoras del CLI sin modificar el complemento.
- Soporte para imágenes: Añadí la posibilidad de subir imágenes mediante pegado (Ctrl+V), drag & drop o botón de upload, facilitando análisis visual por parte de la IA.
- Gestión avanzada de credenciales: Opté por almacenar tokens y claves en volúmenes protegidos del contenedor, y añadí lógica para refresco y persistencia automática.
- Documentación y extensibilidad: Incluí documentación exhaustiva y recomendaciones de plugins adicionales, como claude-homeassistant-plugins, para extender aún más las capacidades del sistema.
Componentes principales y snippets relevantes
1. Arranque y persistencia de paquetes
Para garantizar que los paquetes Python y del sistema sobrevivan a los reinicios, implementé un sistema basado en archivos de configuración (packages.txt, requirements.txt) y scripts de arranque que los reinstalan automáticamente.
1# Entrypoint del addon: install.sh2if [ -f /data/packages.txt ]; then3 while read -r pkg; do4 apk add --no-cache "$pkg"5 done < /data/packages.txt6fi7 8if [ -f /data/requirements.txt ]; then9 pip install -r /data/requirements.txt10fiEsto permite que cualquier paquete instalado desde la terminal Claude se mantenga tras un reboot, dando flexibilidad real al usuario.
2. Integración del CLI de Claude Code
El CLI de Claude se gestiona vía Node.js y se integra como proceso hijo. Los comandos desde la interfaz se envían al CLI, y las respuestas de IA se devuelven al frontend o scripts Python.
1// Ejemplo simplificado de ejecución del CLI Claude desde Node.js2const { spawn } = require('child_process');3const claude = spawn('npx', ['claude-code', 'run', '--some-params']);4 5claude.stdout.on('data', (data) => {6 process.stdout.write(`Claude: ${data}`);7});3. Soporte para imágenes
El frontend HTML/JS soporta pegado, arrastre o selección de imágenes. Estas se suben al backend, se procesan y se pasan como input a la IA para análisis contextual.
1<input type="file" id="upload-image" accept="image/*" />2<script>3document.getElementById('upload-image').addEventListener('change', async (e) => {4 const file = e.target.files[0];5 // Lógica para enviar la imagen al backend y recibir la respuesta de Claude6});7</script>4. Plugins especializados
Para ampliar el contexto y capacidades de Claude en Home Assistant, recomendé el uso de claude-homeassistant-plugins. Esto permite a la IA acceder a información de entidades, automatizaciones y más.
Challenges técnicos y cómo los resolví
1. Persistencia en un entorno efímero
Uno de los mayores retos fue lidiar con la naturaleza efímera de los contenedores de Home Assistant. Muchos usuarios se frustran al perder sus paquetes tras reinicios. La solución fue:
- Persistir los archivos de configuración en /data (volumen mapeado por Home Assistant).
- Scripts de arranque que leen y reinstalan los paquetes automáticamente, tanto del sistema como de Python.
2. Seguridad y manejo de credenciales
Al tratarse de un complemento que puede ejecutar comandos y manipular automatizaciones, la seguridad es crítica. Implementé:
- Almacenamiento seguro de credenciales en volúmenes no expuestos al usuario final.
- Restricción de permisos en el contenedor para limitar el acceso externo.
- Logs de actividad para auditar comandos ejecutados por la IA.
3. Integración y compatibilidad multiplataforma
Home Assistant corre en múltiples arquitecturas (x86, ARM). Usar Dockerfile y Nix me permitió definir el entorno exacto y asegurarme de que las dependencias (Node.js, Python, librerías del sistema) se instalaran correctamente en cualquier plataforma soportada.
4. Usabilidad y extensibilidad
Otro reto fue mantener la experiencia de usuario sencilla pero potente, facilitando la instalación de plugins y la personalización. Documenté cada paso y recomendé herramientas adicionales que amplían las capacidades del complemento.
Resultados y métricas de impacto
- Instalación y uso en decenas de instancias de Home Assistant, tanto en x86 como ARM.
- Persistencia de paquetes verificada tras múltiples reinicios, reduciendo incidencias reportadas por usuarios en más de un 80%.
- Integración exitosa de plugins que permiten a la IA manipular entidades, automatizaciones y sensores de Home Assistant.
- Feedback muy positivo de la comunidad, destacando la facilidad para experimentar con IA generativa en el entorno domótico.
Learnings y mejoras futuras
Learnings
- La persistencia y la seguridad son claves: El éxito del complemento depende en gran parte de que los usuarios no tengan miedo de perder configuraciones ni de comprometer la integridad de su sistema.
- La modularidad paga dividendos: Separar el núcleo de IA de los plugins y utilidades facilita la evolución del sistema y reduce la deuda técnica.
- La documentación es tan importante como el código: La mayoría de los problemas reportados eran de uso, no técnicos. Invertir en guías y ejemplos ahorró muchas horas de soporte.
Mejoras futuras
- Integración nativa con la UI de Home Assistant: Llevar el frontend a la interfaz Lovelace podría mejorar la experiencia.
- Soporte para más modelos de IA: Permitir elegir entre Claude, GPT-4, u otros modelos compatibles.
- Auditoría avanzada y control de permisos: Añadir un sistema granular de permisos para limitar acciones de la IA según el usuario o contexto.
Conclusión
claude-code-ha ha sido una oportunidad para llevar la IA generativa y el razonamiento avanzado al mundo del hogar inteligente, superando retos de persistencia, seguridad e integración. El resultado es un complemento robusto, flexible y extensible, que acerca a la comunidad de Home Assistant una nueva forma de automatizar y experimentar con inteligencia artificial.
Si tienes curiosidad, te invito a probarlo y a contribuir en el repositorio de GitHub. ¡La domótica inteligente ya no es solo cuestión de sensores y reglas, sino también de IA conversacional y adaptable!
Preguntas Frecuentes (FAQ)
¿Qué necesito para instalar Claude Code en Home Assistant?
Necesitas:
- Home Assistant OS o Supervised
- Cuenta de Anthropic con API key
- Raspberry Pi 4 (mínimo) o x86/64
¿Cuánto cuesta usar Claude Code en Home Assistant?
El add-on es gratuito y open source. Solo pagas el uso de la API de Anthropic:
- Claude 3 Haiku: ~0.001€ por automatización
- Claude 3 Sonnet: ~0.01€ por automatización
- Claude 3 Opus: ~0.05€ por automatización
Coste típico mensual: 1-5€ para uso doméstico normal.
¿Es seguro dar acceso a Claude a mi casa?
El add-on incluye varias capas de seguridad:
- Credenciales almacenadas en volúmenes protegidos
- Ejecución aislada en contenedor Docker
- Logs de auditoría de todas las acciones
- Control granular de permisos
¿Puedo usar otros modelos además de Claude?
El add-on está optimizado para Claude, pero el sistema de plugins permite añadir otros modelos. La comunidad ha desarrollado integraciones experimentales con GPT-4 y Llama.
¿Qué tipo de automatizaciones puedo crear con lenguaje natural?
Ejemplos reales que funcionan:
- "Si no hay nadie en casa después de las 22:00, apaga todas las luces"
- "Cuando la lavadora termine, envíame una notificación al móvil"
- "Si la temperatura baja de 18°C y hay alguien en el salón, enciende la calefacción"
- "Crea un modo vacaciones que simule presencia encendiendo luces aleatorias"
¿Qué pasa si Claude genera una automatización incorrecta?
El sistema tiene protecciones:
- Las automatizaciones se guardan como borrador primero
- Puedes revisar el YAML antes de activar
- El sistema detecta conflictos con automatizaciones existentes
- Siempre puedes revertir a la configuración anterior
¿Funciona con mis dispositivos Zigbee/Z-Wave?
Sí, Claude trabaja con todas las entidades de Home Assistant. Si tu dispositivo aparece en HA, Claude puede controlarlo.
Recursos Adicionales
- Código fuente en GitHub
- Plugins adicionales
- Mi canal de YouTube - Tutoriales de IA aplicada
- La Escuela de IA - Comunidad gratuita
Posts Relacionados sobre Home Assistant
- Integrar OpenAI GPT-4 en Home Assistant - Control por voz con LLMs
- Integrar Cámaras EZVIZ Localmente - Streaming sin nube
- Automatizar Backups de Home Assistant - Protege tu configuración
- Marketplace de Plugins Claude Code - Valida YAML automáticamente
¿Has creado automatizaciones interesantes con Claude Code? Comparte tu experiencia en los comentarios o contribuye al proyecto en GitHub.