Home Assistant setups evolve over time—entities can disappear, and services/actions may be renamed by integrations. Watchman helps you spot these changes early by scanning your configuration for references to missing or renamed entities, so you can fix issues before automations break.

Discussion on Home Assistant Community Forum

1. Go to the "Integrations" section on HACS, click "Explore and download repositories" and search for "watchman", then click "Download this repository with HACS".
2. Restart Home Assistant, go to Settings->Devices & Services->Add Integration and select Watchman integration. If integration not found, try to empty your browser cache and reload page.
3. Go to Developer Tools -> Actions, type watchman and select Watchman: report action then press "Perform Action" button. Check watchman_report.txt file in your configuration directory.

Refer to the Configuration section for further fine-tuning.

Watchman is a custom integration for Home Assistant that scans your YAML configuration files and collects referenced entities (sensors, timers, input_select, etc.) and services/actions. It then checks each entity’s current state and reports those that are missing or unavailable. For services/actions, it verifies that they exist in Home Assistant’s registry. The result can be saved as a nicely formatted text table or sent via your preferred notification method (unless the notification target itself is missing 😄). See an example of a report below.

Watchman intentionally keeps the parsing logic lightweight. It doesn’t build a full model of your configuration or try to understand dependencies between files, automations, and templates. Instead, it reads YAML files line by line and uses regex-based heuristics to detect entity and service/action references. Because of this, it may produce false positives (something looks like a reference, but isn’t) and false negatives (a real reference isn’t detected). You can silence false positives using Ignored entities and actions (see the Configuration section). Reducing false negatives is an ongoing improvement area.

Watchman does not try to discover every missing or unavailable entity in your Home Assistant instance. It only reports entities and services/actions that it can find referenced in your YAML configuration (automations, scripts, dashboards, templates, etc.).

Watchman configuration is currently split between two locations:

• Integration Options: Used for general setup. Path: Settings > Devices & Services > Watchman > Configure (General settings marked with ⚙️ below).
• Device Controls: Used for dynamic settings (e.g., ignored labels). Path: Settings > Devices & Services > Devices > Watchman (Dynamic settings marked with 🎛️ below).

The distinction between static and dynamic configuration is provisional and may change in future updates.

• Ignore a file: */automations.yaml
• Ignore all files in the folder: /config/esphome/*
• Ignore several folders: /config/custom_components/*, /config/appdaemon/*, /config/www/*

• Ignore an entity: person.dummylabs
• Ignore everything in sensor domain: sensor.*
• Ignore any entity/action which name ends with "_ble": *.*_ble

The text version of the report can be generated using watchman.report action from Developer Tools UI, an automation or a script. Default location is /config/thewatchman_report.txt, which can be changed in the UI configuration. A long report can be split into several messages (chunks) due to limitations imposed by some notification actions (e.g., telegram). Action behaviour can be altered with additional optional parameters:

action: watchman.report
data:
  parse_config: true
  action: persistent_notification.create
  data:
    title: Watchman Report
  chunk_size: 3500
  create_file: true`

Besides of the report, integration provides a few sensors which can be used within automations or dashboards:

• sensor.watchman_missing_entities
• sensor.watchman_missing_actions
• sensor.watchman_last_updated

Please note that the ASCII table format is only used when report is saved to a file. For notification actions watchman uses plain text list due to presentation limitations.

-== WATCHMAN REPORT ==-

-== Missing 1 action(s) from 38 found in your config:
+--------------------------------+---------+------------------------------------------+
| Action                         | State   | Location                                 |
+--------------------------------+---------+------------------------------------------+
| xiaomi_miio.vacuum_goto        | missing | automations.yaml:599,605                 |
+--------------------------------+---------+------------------------------------------+

-== Missing 3 entity(ies) from 216 found in your config:
+--------------------------------+---------+------------------------------------------+
| Entity                         | State   | Location                                 |
+--------------------------------+---------+------------------------------------------+
| sensor.stats_pm25_10_median    | unavail | customize.yaml:14                        |
| sensor.xiaomi_miio_sensor      | unavail | automations.yaml:231,1348                |
| vacuum.roborock_s5max          | unavail | automations.yaml:589,603,610,1569        |
+--------------------------------+---------+------------------------------------------+

-== Report created on 03 Feb 2022 17:18:55
-== Parsed 200 files in 0.96s., ignored 66 files
-== Generated in: 0.01s. Validated in: 0.00s.

The legend at the bottom of the report shows time consumed by 3 coherent stages: parse configuration files, validate each entity/action state and generate text version of the report.