hass-circadian_lighting: shifting Home Assistant lights along with the sun

The problem: a home lit the same way at noon and at midnight

Most smart lighting setups are static. A bulb is set to a warm white at 4000 kelvin, and it stays there through the afternoon, the evening and the small hours, because that is the value someone chose once and stored.

Circadian Lighting is a Home Assistant custom component that takes a different approach. It slowly synchronises colour changing lights with the naturally occurring colour temperature of the sky across the day, so the environment has cooler hues during the midday and warmer tints near twilight and dawn. The change is gradual rather than switched, and that is the whole design: your eyes adapt to a slowly shifting light rather than to a lamp that flips between two settings.

The audience is a Home Assistant user who already has colour changing lights and cares about sleep and wake routines. The repository topics name circadian rhythms, lighting, sleep and wellness, and the component leans on research links the project collects in an expandable section, including pages from the National Institute of General Medical Sciences and the National Sleep Foundation.

The component also has a sleep mode, which sets the lights to a cool white at one percent brightness. The project describes that as far brighter than starlight but says it will not reset your circadian rhythm or break down too much rhodopsin in your eyes. That is a physiological claim from the project description, not a measured result, and it is worth holding at that distance.

The mechanism: sun position turned into three numbers

The component computes its values from the sun's position, and the project publishes the three resulting series as graphs: a percentage for sun position, a colour temperature value, and a brightness value. Those graphs are described as generated using the values calculated by the Circadian Lighting sensor or switch, which tells you the component exposes its own calculated values as entities rather than only mutating lights.

That distinction is the useful architectural point. A switch that only writes to lights is a black box: you cannot see what it computed, and you cannot build automations on top of it. Here there is a sensor side and a switch side, so the computed colour temperature and brightness are available to inspect and to reuse in your own automations.

The switch writes to lights through one of several colour spaces, and the component groups your entities by which one they understand. lights_ct takes a list of light entities that should be set in mireds, which is the colour temperature path. lights_rgb takes entities set in RGB, and lights_xy takes entities set in XY. lights_brightness takes entities that should only have brightness adjusted, with no colour change at all.

The colour temperature path is the one to think hardest about. Mireds are the inverse scale of kelvin, so a single mired value maps to a range of warm light, and a bulb that reports its colour temperature in kelvin has to be converted. The project documentation does not describe the mapping curve, the update interval, or how the component decides when to write a new value, so the detail is worth confirming against the wiki before you rely on it.

Installing it: HACS, a custom updater, or a manual copy

The installation is the standard custom component route, and the project lists three ways in. The first is HACS, the Home Assistant Community Store, and the repository carries a hacs.json file along with a HACS default badge, which marks the integration as available in the default store rather than requiring a custom repository to be added by hand.

The second route is a custom updater, and the third is a manual installation, where the custom_component files are copied into your Home Assistant configuration directory yourself. All three point at the installation instructions page in the project wiki.

The component configuration itself is minimal. The example configuration.yaml entry is:

# Example configuration.yaml entry
circadian_lighting:

There are no required keys there, which tells you the component starts with sensible defaults and the tuning happens in the switch configuration and in the advanced options.

The repository is small by design. The top-level entries are the custom_components/ directory, hacs.json, info.md for the store listing, a pyproject.toml, a LICENSE, and the README. The pyproject declares the project name hass-circadian_lighting, a dynamic version, and requires-python of 3.8 or higher, with ruff configured to a line length of 90. There is no test directory and no CI configuration beyond the .github/ directory, so the code quality story here is linting and manual use rather than an automated suite.

Configuring a switch and picking one colour space

The switch configuration is where the decisions are made. The example given in the documentation is:

# Example configuration.yaml entry
switch:
  - platform: circadian_lighting
    lights_ct:
      - light.desk
      - light.lamp

The switch takes an optional name, which is what Home Assistant displays for the entity, and then four optional lists of light entities. The order of the entity lists is the interesting design choice, because a light can appear in more than one of them, and each list triggers a different colour space. A bulb listed under lights_ct gets a colour temperature in mireds. A bulb under lights_rgb gets an RGB value. A bulb under lights_xy gets an XY value. A bulb under lights_brightness has only its brightness changed, with no colour command at all.

That fourth list is the one to use carefully. A light that only has brightness adjusted will not follow the colour temperature curve, so in a room where some fixtures are dimmable only and others are full colour, the room will not be a single colour.

The advanced configuration is documented separately in the wiki, under the component configuration variables and the switch configuration variables, and the project links to that page from both blocks. Since the README carries only the four list variables and defers everything else to the wiki, a reader who wants the min and max bounds, the transition speed or the sunrise and sunset offsets will have to follow the link.

The sleep mode and the limits of what the component claims

The sleep mode is the feature that distinguishes this component from a plain colour temperature schedule. It sets the lights to a cool white at one percent brightness, and the project argues that this level is bright enough to be useful while avoiding the effect of a bright light on the body's clock.

That is a nice piece of product thinking, and it is also the point where the documentation thins out. The project description explains what sleep mode does, but it does not specify how the mode is entered, whether it is a separate switch, or what happens when it ends. The wiki is where that detail has to come from.

Another limit is the dependency on the sun position. The component's whole model is a mapping from the sky's colour temperature at your location to your lights, which means it is tied to sunrise and sunset, and to your local time zone and latitude. The graphs in the README are labelled with sun position, colour temperature and brightness, so the chain of computation is visible, but the exact formula is not published in the repository.

There is also a maintenance question that a reader should settle early. The releases are 2.1.6 from 2025-09-19, a 2.1.7 beta from 2026-10-15 and 2.1.7 from 2026-10-20, and the last push was on 2026-10-20. So the project is moving, and it does publish betas through the store. A beta release that reaches your Home Assistant instance through the default HACS channel is something to be aware of rather than something to opt into deliberately.

Licence, home for the code, and how to decide

The component is under the Apache-2.0 licence, which is a permissive licence with an express patent grant, and the LICENSE file sits at the repository root. The project has no homepage outside GitHub, and the wiki linked from the README is the real documentation: installation instructions, advanced configuration and the acknowledgements page all live there.

That arrangement is typical of a community Home Assistant integration, and it has a practical consequence. The repository is small, the code is a custom component under custom_components/, and the documentation is deliberately external and wiki-based, which means it is edited without a pull request and can change independently of the code. Anyone pinning a version for a production home should read the wiki page for that version rather than the current one.

So the decision is fairly simple. If you run Home Assistant, own colour changing lights, and would rather the house tracked the sky than a static schedule, this component does that with one switch and no cloud service, and it installs in a few minutes through HACS. If you need the colour temperature to follow something other than the sun, if your lights are dimmable only, or if you want a component with an automated test suite behind it, this is not the one to pick, and the wiki is the place to confirm before you rely on the sleep mode behaviour.

Editorial conclusion

Adopt hass-circadian_lighting if you run Home Assistant, have colour changing lights, and want the colour temperature of your home to follow the sky rather than a fixed schedule you maintain by hand. Do not adopt it expecting documented, tested behaviour, since the repository holds no test suite and the detailed documentation sits in the wiki. Before you install it, check that your lights accept mired, RGB or XY values, and decide which of the three colour paths suits your bulbs, because the component sets each group of lights through a different colour space and mixing them gives inconsistent results.

Frequently asked questions

Official sources

1. claytonjn/hass-circadian_lighting on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases