Clockwork is a custom integration for Home Assistant that provides advanced date, time, and duration calculations. Create sensors and binary sensors for measuring timespans, checking date ranges, detecting seasons, and triggering time-based automations.
- Timespan Calculations: Calculate duration since an entity changed state, with configurable tracking modes
- Offset Calculations: Time-delayed triggers with pulse, duration, and latch modes
- Datetime Offset: Apply time offsets to datetime entities for scheduling
- Date Range Duration: Measure duration between two datetime entities
- Attribute Monitor: Extract and expose entity attributes as dedicated sensors for automation and display
- Season Detection: Detect current season automatically
- Month Detection: Check if current date falls in specified months
- Holiday Countdowns: Built-in US holidays plus custom holiday support
- Date Range Checks: Determine if current time is within or outside a range
- Custom Automation Conditions: Duration-based conditions for automations (check how long since entity changed or automation was last triggered)
- Calendar Services: Get, update, and delete calendar events (requires calendar integration)
- No YAML Required: All configuration through intuitive Home Assistant UI
- Real-time Updates: Configurable update intervals for time-based sensors
- Flexible Triggering: Control which state changes trigger offset calculations
- Timezone Aware: Automatic timezone handling for datetime comparisons
For detailed guides and examples for each calculation type, visit the Clockwork Wiki:
| Topic | Link |
|---|---|
| Getting Started | Home |
| Timespan Calculation | Calculate duration since state change |
| Offset Calculation | Time-delayed triggers |
| Datetime Offset | Apply time offsets to datetime entities |
| Date Range Duration | Measure duration between dates |
| Attribute Monitor | Extract and expose entity attributes |
| Season Detection | Detect current season automatically |
| Month Detection | Check if current date is in specified months |
| Holiday Countdown | Days until next holiday |
| Custom Holidays | Define your own holidays |
| Between/Outside Dates | Date range checks |
| Custom Automation Conditions | Duration-based automation conditions |
| Scan Automations | Discover time-based automations |
| Calendar Services | Manage calendar events |
Clockwork creates different types of sensors depending on the calculation type:
Create countdown sensors for holidays and special dates:
- Open HACS in Home Assistant
- Click "Custom repositories" in the top right
- Add this repository:
- Repository URL:
https://github.com/mutilator/clockwork - Category: Integration
- Repository URL:
- Click "Install"
- In Home Assistant, go to Settings > Devices & Services
- Click Create Automation and search for "Clockwork"
- Follow the setup wizard
- Download the latest release
- Unzip and copy the
clockworkfolder to:~/.homeassistant/custom_components/ - Restart Home Assistant
- Go to Settings > Devices & Services > Create Automation and search for "Clockwork"
All configuration is done through the Home Assistant UI. No YAML editing required!
- Go to Settings > Devices & Services > Clockwork
- Select Configure
- Choose from:
- Add Calculation - Create a new sensor or binary sensor
- Modify Calculation - Edit existing calculations
- Delete Calculation - Remove calculations
- Add Custom Holiday - Define custom holidays for countdowns
- Modify Custom Holiday - Edit existing custom holidays
- Delete Custom Holiday - Remove custom holidays
- Timespan - Measure duration since state change
- Offset - Trigger after elapsed time
- Datetime Offset - Apply time offset to datetime
- Date Range Duration - Measure duration between two datetimes
- Season Detection - Detect spring, summer, autumn, or winter
- Month Detection - Check specific months
- Holiday Countdown - Days until US holidays or custom dates
- Between Dates - True when current time is within range
- Outside Dates - True when current time is outside range
Discover which of your automations use time or date-based triggers and conditions. This helps you identify automations that could benefit from Clockwork calculations.
How to use:
- Go to Settings > Devices & Services > Clockwork > Configure
- Select Scan Automations for Time Patterns
- Results display immediately showing automations with time/date patterns
Or call the service directly:
- Go to Developer Tools > Services
- Call
clockwork.scan_automations - Results show in logs and notifications
See Scan Automations wiki page for details.
To see Clockwork in action, use an Offset Calculation for a garage door alert:
Traditional Approach (with delays and conditions):
automation:
- alias: "Garage Door Alert"trigger:
platform: stateentity_id: binary_sensor.garage_doorto: "on"action:
- delay: "00:30:00"# Wait 30 minutes
- condition: stateentity_id: binary_sensor.garage_doorstate: "on"# Still open?
- service: notify.send_alertdata:
message: "Garage door has been open for 30 minutes"With Clockwork (simple, robust, restart-safe):
Create an Offset Calculation:
- Name: "Garage Door Open 30min"
- Entity:
binary_sensor.garage_door - Time Offset: "30 minutes"
- Behavior Mode: "pulse" (alert once) or "duration" (stay active while alert is relevant)
- Trigger Event: "on"
Simplify your automation:
automation:
- alias: "Garage Door Alert"trigger:
platform: stateentity_id: binary_sensor.garage_door_open_30minto: "on"action:
service: notify.send_alertdata:
message: "Garage door has been open for 30 minutes"Key Benefit: The offset calculation survives Home Assistant restarts — the 30-minute timer continues accurately even if HA restarts. No delays, no conditions, no hassle.
For more examples and walkthroughs, see the wiki.
- Issue Tracker: GitHub Issues
- License: MIT License - See LICENSE for details
Clockwork is built to integrate seamlessly with Home Assistant and follows all Home Assistant custom component standards.
Ready to get started? Head over to the wiki for detailed guides and examples!