lukab-dev/ha-layers

Let automations borrow a light and give it back, without snapshots.

You're watching a film, so an automation turns the sofa lamp off. Halfway through, the washer finishes and another automation turns the same lamp orange to tell you. You empty the washer. What should the lamp do now?

It should go back to off, because the film is still on. When the film ends, it should go back to how you had it before.

Home Assistant doesn't do that on its own. The usual trick is to save a scene, change the lights, then restore the scene later. That breaks easily: the saved scene is gone after a restart, the restore undoes whatever someone changed in the meantime, and two automations borrowing the same lamp restore each other's leftovers.

Layers solves it by stacking. Each automation puts a layer on the light and removes it when it's done. The light always shows the top layer, and when that one is removed it shows the next one down, as it is now. Nothing is saved or restored, so nothing can go stale.

   priority 70   washer    orange        ← the lamp shows the top layer
   priority 40   tv        off
   ───────────── base      on, 60 %      ← how you left it

• Automations stop fighting each other. Higher priority wins; removing a layer reveals the one below.
• People always win. If someone changes a light by hand (switch, app, voice), Layers keeps their setting and gets out of the way on that light.
• Survives restarts. Layers and their timers are stored.
• Makes sure commands arrive. It checks each light after sending a command, retries if needed, and catches up with lights that were offline.
• A timer never lights a dark room. When a layer runs out, it may only turn a light off or dim it.
• Opt-in. Only the lights you choose are managed, and only through Layers' own actions. Your other automations and scenes keep working as they are.

1. In HACS, add https://github.com/lukab-dev/ha-layers as a custom repository (type Integration) and install Layers. Or copy custom_components/layers into your config/custom_components/ folder.
2. Restart Home Assistant.
3. Go to Settings → Devices & services → Add integration → Layers and pick the lights it should manage. Switches (smart plugs, relays) work too, as on/off lights.

Needs Home Assistant 2026.7 or newer.

Layers starts in watch-only mode. The Apply switch (switch.layers_apply) is off, so it works out what it would do but doesn't touch your lights. Try your automations, check the Activity log, and turn Apply on when you're happy.

The quickest start is the blueprint, which dims a room while a TV or speaker plays:

Or write it yourself. Borrowing a light takes one action, and giving it back takes another:

# The film starts: turn the living room lamps off
action: layers.set
target:
  entity_id: [light.floor_lamp, light.sofa_lamp]
data:
  layer: tv          # any name you like
  priority: 40       # 1-99, higher wins
  state: "off"
  transition: 10

# The film ends: give the lamps back
action: layers.clear
data:
  layer: tv

When tv is cleared, each lamp goes back to whatever is below it: another layer, or simply how it was set before.

- alias: "TV: dim the room while playing"
  triggers:
    - trigger: template
      value_template: "{{ is_state('media_player.living_room_tv', 'playing') }}"
      for: "00:00:15"
      id: play
    - trigger: template
      value_template: "{{ not is_state('media_player.living_room_tv', 'playing') }}"
      for: "00:02:00"
      id: stop
  actions:
    - choose:
        - conditions: [{condition: trigger, id: play}]
          sequence:
            - action: layers.set
              target: {entity_id: [light.floor_lamp, light.sofa_lamp]}
              data: {layer: tv, priority: 40, state: "off", transition: 10,
                     ttl: "06:00:00", owner: tv_dim}
            - action: layers.set    # dim the dining lamp only if it is already on
              target: {entity_id: light.dining_pendant}
              data: {layer: tv, priority: 40, mode: adjust, brightness_pct: 25,
                     transition: 10, ttl: "06:00:00", owner: tv_dim}
        - conditions: [{condition: trigger, id: stop}]
          sequence:
            - action: layers.clear
              data: {layer: tv, transition: 3}

- alias: "Washer done: sofa lamp orange"
  triggers:
    - trigger: state
      entity_id: sensor.washer_status
      to: finished
  actions:
    - action: layers.set
      target: {entity_id: light.sofa_lamp}
      data: {layer: washer, priority: 70, state: "on", xy_color: [0.679, 0.318],
             brightness_pct: 100, ttl: "04:00:00", owner: washer_done}

- alias: "Washer emptied: give the lamp back"
  triggers:
    - trigger: state
      entity_id: input_button.washer_emptied
  actions:
    - action: layers.clear
      target: {entity_id: light.sofa_lamp}
      data: {layer: washer, transition: 2}

A layer has a name, a priority from 1 to 99, and what the light should do. Each light shows its highest-priority layer. A light can hold one layer per priority.

The base is what a light shows when it has no layers. You never set it directly: it is simply how people and your other automations leave the light.

Three kinds of layer:

• set (the default): decides on or off, plus any brightness or colour you give it. Anything you leave out comes from the layer below.

• mode: adjust: only changes brightness or colour, and only on a light that is already on. It never turns a light on. Use it for "dim whatever is lit to 25 %".

• mode: follow with a source: like adjust, but the brightness and colour come from another entity's attributes and change when it does. Point it at an Adaptive Lighting switch or a template sensor; Layers does no circadian maths itself. Give it a low priority, so a TV dim or a nightlight sits above it:

  action: layers.set
  target: {entity_id: [light.sofa, light.reading]}
  data: {layer: circadian, priority: 10, mode: follow,
         source: switch.adaptive_lighting_living_room}

  Every update of the source reaches the layer, but a light is only sent a command when the new values no longer match what it shows, within the same tolerances Layers uses everywhere: 100 K of colour temperature, 5 of 255 brightness, 0.03 in xy. Adaptive Lighting updates every 90 s by default and moves a few kelvin each time, so a light typically gets a new colour every 10 minutes or so, in steps of about 100 K. That is deliberate: steps that size are hard to see, and it keeps commands to the lights down.

Timers: give a layer a ttl ("06:00:00") or an until (a time) as a safety net in case the clear never comes. Setting the same layer again restarts the timer. When the timer runs out, the layer may only turn the light off or dim it. If removing it would light up or brighten a room, the light stays as it is instead. (on_expire: render turns that rule off.) A layers.clear always restores fully.

Layers can tell its own commands apart from everything else. Anything else that changes a managed light counts as "someone": a person at the switch, the app, voice, a scene, or another automation. A scene counts even for a light it didn't need to change: Home Assistant sends nothing to a light that already looks the way the scene wants, and Layers treats that light as if the scene had set it.

By default (Take it back), their change wins. It becomes the light's new base, and the layers on that light are removed, on that light only. The automation can't put the same layer back on that light until it has cleared it. So when the film ends, the lamp you turned on mid-film stays exactly as you set it.

You can choose a different behaviour in the integration's options, for all lights or per light:

Follow layers are never removed by someone's change. Only what the person changed stops following: dim a light by hand and its brightness stays where you put it while its colour keeps adapting. It follows again once the light is turned off, or after manual_timeout if the layer sets one. A light switched on without a brightness or colour (a wall switch, voice, a button) gets the follow values straight away; one turned on at 30 % keeps its 30 %.

layers.set options: layer, priority (needed the first time a layer goes on a light), mode, state, brightness / brightness_pct, color_temp_kelvin, xy_color / hs_color / rgb_color, transition, ttl / until, on_expire, resume_after_manual, only_if_present and owner; for mode: follow, source and manual_timeout (transition is then the transition of each update, 1 s by default). The action's UI form describes each one.

• switch.layers_apply: off means watch-only. Layers still keeps track of everything but sends nothing.
• sensor.layers_status: ok, pending (still delivering), failed or shadow (watch-only).

The Activity log shows which layer changed a light, and on whose behalf.

python -m pytest tests/logic                  # decision logic, any Python >= 3.12
uv venv --python 3.14 .venv-ha && uv pip install --python .venv-ha/bin/python -r requirements_test.txt
.venv-ha/bin/python -m pytest tests/ha        # the integration inside Home Assistant

The decisions live in custom_components/layers/logic/, which has no Home Assistant imports, so it can be tested directly and replayed against recorded history. The full specification is docs/SPEC.md.

main is always the latest stable release. New work lands on beta, and pre-releases (0.2.0b1) are tagged there. A stable release merges beta into main; drop the "This is the beta branch" note from Install when it does.

MIT.