Hassette

A simple, modern, async-first Python framework for building Home Assistant automations.

Documentation: https://hassette.readthedocs.io

✨ Why Hassette?

• Type Safe: Full type annotations with Pydantic models and comprehensive IDE support
• Async-First: Built for modern Python with async/await throughout
• Dependency Injection: Clean handler signatures with automatic parameter extraction
• Simple & Focused: Just Home Assistant automations - no complexity creep
• Developer Experience: Clear error messages, proper logging, hot-reloading, and intuitive APIs

🚀 Quick Start

Install Hassette:

pip install hassette

Create a simple app (apps/hello.py):

from typing import Annotated
from hassette import App, states
from hassette import dependencies as D

class HelloApp(App):
    async def on_initialize(self):
        self.bus.on_state_change(
            "binary_sensor.front_door",
            handler=self.on_door_open,
            changed_to="on"
        )

    async def on_door_open(
        self,
        new_state: D.StateNew[states.BinarySensorState],
        entity_id: D.EntityId,
    ):
        self.logger.info("%s opened!", entity_id)
        await self.api.call_service(
            "notify", "mobile_app_phone",
            message=f"{new_state.attributes.friendly_name or entity_id} opened!"
        )

Configure it (config/hassette.toml):

[hassette]
base_url = "http://homeassistant.local:8123"

[apps.hello]
filename = "hello.py"
class_name = "HelloApp"

Run it:

uv run hassette

See the Getting Started guide for detailed instructions.

🔄 Coming from AppDaemon?

Check out our dedicated comparison guide:

• AppDaemon Comparison

📖 More Examples

Check out the examples/ directory for complete working examples:

Based on AppDaemon's examples:

• Battery monitoring - Monitor device battery levels
• Presence detection - Track who's home
• Sensor notifications - Alert on sensor changes

Real-world apps:

• Office Button App - Multi-function button handler
• Laundry Room Lights - Motion-based lighting

Configuration examples:

• Docker Compose Guide - Docker deployment setup
• HassetteConfig - Complete configuration reference

🛣️ Status & Roadmap

Hassette is under active development. We follow semantic versioning and recommend pinning a minor version (e.g., hassette~=0.x.0) while the API stabilizes.

Development is tracked in our GitHub project. Open an issue or PR if you'd like to contribute!

What's Next?

• 🔐 Enhanced type safety - Fully typed service calls and additional state models
• 🏗️ Entity classes - Rich entity objects with built-in methods (e.g., await light.turn_on())
• 💾 State cache - Local state caching for faster reads (similar to AppDaemon)
• 🔄 Enhanced error handling - Better retry logic and error recovery
• 🧪 Testing improvements - More comprehensive test coverage and user app testing framework

🤝 Contributing

Contributions are welcome! Whether you're:

• 🐛 Reporting bugs or issues
• 💡 Suggesting features or improvements
• 📝 Improving documentation
• 🔧 Contributing code

See CONTRIBUTING.md for guidelines on getting started.

📄 License

MIT