{"id":13580664,"url":"https://github.com/dummylabs/thewatchman","last_synced_at":"2025-06-12T20:34:08.084Z","repository":{"id":37422154,"uuid":"455174197","full_name":"dummylabs/thewatchman","owner":"dummylabs","description":"Home Assistant custom integration to keep track of missing entities and actions in your config files","archived":false,"fork":false,"pushed_at":"2024-12-06T14:52:39.000Z","size":557,"stargazers_count":537,"open_issues_count":44,"forks_count":23,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-05-22T17:14:15.766Z","etag":null,"topics":["automation","home-assistant","homeassistant"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dummylabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-03T13:23:56.000Z","updated_at":"2025-05-07T01:38:38.000Z","dependencies_parsed_at":"2024-06-19T23:08:42.203Z","dependency_job_id":"f257101d-6028-4329-bed7-50c5a404117b","html_url":"https://github.com/dummylabs/thewatchman","commit_stats":{"total_commits":247,"total_committers":14,"mean_commits":"17.642857142857142","dds":0.06882591093117407,"last_synced_commit":"655884040b4623306284ab5e91a2771c085737f2"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/dummylabs/thewatchman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dummylabs%2Fthewatchman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dummylabs%2Fthewatchman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dummylabs%2Fthewatchman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dummylabs%2Fthewatchman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dummylabs","download_url":"https://codeload.github.com/dummylabs/thewatchman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dummylabs%2Fthewatchman/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259522456,"owners_count":22870469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","home-assistant","homeassistant"],"created_at":"2024-08-01T15:01:54.065Z","updated_at":"2025-06-12T20:34:08.046Z","avatar_url":"https://github.com/dummylabs.png","language":"Python","funding_links":[],"categories":["Install from Source","Python","automation","Custom Integrations"],"sub_categories":["Smart Home Automation","Alternative Dashboards"],"readme":"# The Watchman\n[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/custom-components/hacs)\n![version](https://img.shields.io/github/v/release/dummylabs/thewatchman)\n[![Community Forum][forum-shield]][forum]\n\n\nThe world around us is constantly changing, and so is Home Assistant. How often have you found yourself in a situation where your automations stopped working because some entities became permanently unavailable or actions changed their names? Some integrations can easily change the name of its actions and sensors they expose to Home Assistant. The watchman is an attempt to control such unwelcome changes and enable you to react proactively before any critical automation gets broken.\n\n[Discussion on Home Assistant Community Forum](https://community.home-assistant.io/t/watchman-keeps-track-of-missing-entities-and-services-in-your-config-files/390391)\n\n## Quick start\n\n1. Go to the \"Integrations\" section on HACS, click \"Explore and download repositories\" and search for \"watchman\", then click \"Download this repository with HACS\".\n2. Restart Home Assistant, go to Settings-\u003eDevices \u0026 Services-\u003eAdd Integration and select Watchman integration. If integration not found, try to empty your browser cache and reload page.\n3. Go to Developer Tools -\u003e Actions, type `watchman` and select `Watchman: report` action then press \"Perform Action\" button. Check `watchman_report.txt` file in your configuration directory.\n\nRefer to the [Configuration section](https://github.com/dummylabs/thewatchman#configuration) for further fine-tuning.\n\n## What does it do\nThe Watchman is a custom integration for Home Assistant that collects all entities (sensors, timers, input_selects, etc.) mentioned in your YAML configuration files, as well as all actions. It checks the actual state of each entity one by one and reports those that are unavailable or missing. For actions, it verifies their availability in the Home Assistant actions registry. The report can be stored as a nicely formatted text table or sent via your chosen notification method (unless the notification method itself is missing :smile:). Check out an [example of a report](https://github.com/dummylabs/thewatchman#example-of-a-watchman-report) below.\n\nThe integration has very simple internals. It knows nothing about complex relationships and dependencies among YAML configuration files, nor about the semantics of entities and automations. It parses YAML files line by line and tries to guess references either to an entity or an action based on regular expression heuristics. This means the integration can produce both false positives (when it looks like a duck, but is not) and false negatives (when some entity in a configuration file is not detected by the integration). To ignore false positives, the **Ignored entities and actions** parameter can be used (see Configuration section below). Improvements for false negatives are a goal for future releases.\n\n## What is does not do\nThe Watchman will not report every unavailable or unknown entities within your system — only those that are actively used by Home Assistant, whether it is an automations, dashboard configuration, template sensor, etc.\n\n## Configuration Options\n\nIntegration settings are available in Settings-\u003eDevices \u0026 Services-\u003eWatchman-\u003eConfigure\n\n[![Open your Home Assistant instance and show your integrations.](https://my.home-assistant.io/badges/integrations.svg)](https://my.home-assistant.io/redirect/integrations/)\n\nOption | Description | Example\n------------ | ------------- | -------------\nFolders to watch | Comma-separated list of folders to scan for entities and actions recursively. | `/config`\nIgnored entities and actions | Comma-separated list of items to ignore. The entity/action will be excluded from the report if their name matches a rule from the ignore list. Wildcards are supported, see [example](https://github.com/dummylabs/thewatchman?tab=readme-ov-file#ignored-entities-and-actions-formely-known-as-services-option-example) below. | `sensor.my_sensor1, sensor.my_sensor2`\nExclude entity states | Select which states will be excluded from the report | Checkboxes in UI\nIgnored files | Comma-separated list of files and folders to ignore. Wildcards are supported, see [example](https://github.com/dummylabs/thewatchman#ignored-files-option-example) below. Takes precedence over *Included folders* option.| `*/blueprints/*, */custom_components/*, */esphome/*`\nStartup delay | By default, watchman's sensors are updated by `homeassistant_started` event. Some integrations may require extra time for intiialization so that their entities/actions may not yet be ready during watchman check. This is especially true for single-board computers like Raspberry PI. This option allows to postpone startup sensors update for certain amount of seconds. | `0`\nParse UI controlled dsahboards | Parse Dashboards UI (ex-Lovelace) configuration data stored in `.storage` folder besides of yaml configuration. | UI flag\nReport location | Report location and filename. | `/config/watchman_report.txt`\nCustom header for the report | Custom header for watchman report. | `-== Watchman Report ==-`\nReport's column width | Report's columns width. The list of column widths for the table version of the report. | `30, 7, 60`\nAdd friendly names | Add friendly name of the entity to the report whenever possible. | UI flag\n\n### Ignored files option example\n* Ignore a file: `*/automations.yaml`\n* Ignore all files in the folder: `/config/esphome/*`\n* Ignore several folders: `/config/custom_components/*, /config/appdaemon/*, /config/www/*`\n\u003cimg src=\"https://raw.githubusercontent.com/dummylabs/thewatchman/main/images/ignored_files_ui.png\" width=50%\u003e\n\n### Ignored entities and actions example\n* Ignore an entity: `person.dummylabs`\n* Ignore everything in sensor domain: `sensor.*`\n* Ignore any entity/action which name ends with \"_ble\": `*.*_ble`\n\n## Report Action Parameters\nThe 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:\n\n\u003e [!NOTE]\n\u003e Versions prior to 0.6.4 had report parameter named `service`, now it is renamed to `action`. Old parameter name still supported to preserve compatibilty with existing automations.\n\nParameter | YAML key | Description | Default\n------------ | ------------- | -------------| -------------\nForce configuration parsing |`parse_config`| Forces watchman to parse Home Assistant configuration files and rebuild entity and actions list. Usually this is not required as watchman will automatically parse files once Home Assistant restarts or tries to reload its configuration. | `False`\nSend report as notification |`action`| Home assistant notification action to send report via, e.g. `persistent_notification.create`. See compatibility note below.| ``\nNotification action data |`data`| A json object with additional notification action parameters. See [example](https://github.com/dummylabs/thewatchman#send-report-via-telegram-bot) below.  | `None`\nMessage chunk size |`chunk_size`| Maximum message size in bytes. Some notification actions, e.g., Telegram, refuse to deliver a message if its size is greater than some internal limit. If report text size exceeds `chunk_size`, the report will be sent in several subsequent notifications. `0` value will disable chunking. | `3500`\n\n\n### A useless example sending report as persitent notification\n```yaml\naction: watchman.report\ndata:\n  parse_config: true\n  action: persistent_notification.create\n  data:\n    title: Watchman Report\n  chunk_size: 3500\n  create_file: true`\n```\n\n## Sensors\n\n\u003e [!NOTE]\n\u003e Versions prior to 0.6.4 had a sensor named `sensor.watchman_missing_services`. Latest versions use another name: `sensor.watchman_missing_actions` if integration was installed from scratch (new user).\n\u003e Existing users who upgraded from previous versions will have old sensor name to preserve compatibilty with their scripts and dashboards. They can rename sensor themselves or just remove integration and install it again.\n\nBesides of the report, integration provides a few sensors which can be used within automations or dashboards:\n- sensor.watchman_missing_entities\n- sensor.watchman_missing_actions\n- sensor.watchman_last_updated\n\n\n## Example of a watchman report\nPlease 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.\n```\n-== WATCHMAN REPORT ==-\n\n-== Missing 1 action(s) from 38 found in your config:\n+--------------------------------+---------+------------------------------------------+\n| Action                         | State   | Location                                 |\n+--------------------------------+---------+------------------------------------------+\n| xiaomi_miio.vacuum_goto        | missing | automations.yaml:599,605                 |\n+--------------------------------+---------+------------------------------------------+\n\n-== Missing 3 entity(ies) from 216 found in your config:\n+--------------------------------+---------+------------------------------------------+\n| Entity                         | State   | Location                                 |\n+--------------------------------+---------+------------------------------------------+\n| sensor.stats_pm25_10_median    | unavail | customize.yaml:14                        |\n| sensor.xiaomi_miio_sensor      | unavail | automations.yaml:231,1348                |\n| vacuum.roborock_s5max          | unavail | automations.yaml:589,603,610,1569        |\n+--------------------------------+---------+------------------------------------------+\n\n-== Report created on 03 Feb 2022 17:18:55\n-== Parsed 200 files in 0.96s., ignored 66 files\n-== Generated in: 0.01s. Validated in: 0.00s.\n```\nThe 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.\n\n## Markdown card example\nWatchman sensors `sensor.watchman_missing_entities` and `sensor.watchman_missing_actions` have additional set of attributes which makes it possible to create your own report using a lovelace card. Below is an example of missing entities report for the Lovelace markdown card.\n\u003e [!NOTE]\n\u003e For dark mode replace /icon.png to /dark_logo.png.\n\n```yaml\ntype: markdown\ncontent: \u003e-\n  \u003ch2\u003e \u003cimg src=\"https://brands.home-assistant.io/watchman/icon.png\" alt=\"WM Logo\" width=\"32\" height=\"32\"\u003e Watchman report\u003c/h2\u003e\n  \u003ch3\u003eMissing Entities: {{ states.sensor.watchman_missing_entities.state }} \u003c/h3\u003e\n  {%- for item in state_attr(\"sensor.watchman_missing_entities\", \"entities\") %}\n  \u003chr\u003e \u003ctable\u003e\u003ctr\u003e \u003ctd\u003e\n  \u003cha-icon icon='mdi:\n  {%- if item.state==\"missing\"-%}cloud-alert'\n  {%- elif item.state==\"unavail\" -%}cloud-off-outline' {%- else-%}cloud-question'\n  {%- endif -%} \u003e\u003c/ha-icon\u003e\n  {{ item.id }} [{{item.state}}] \u003ca title=\"{{item.occurrences}}\"\u003e\n  {{item.occurrences.split('/')[-1].split(':')[0]}}\u003c/a\u003e\n  \u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n  {%- endfor %}\ncard_mod:\n  style:\n    ha-markdown:\n      $: |\n        ha-markdown-element:first-of-type hr{\n          border-color: #303030;\n        }\n\n```\nImportant considerations:\n1. Make sure you are in code editor mode before pasting this code into the markdown card\n2. `card_mod` section is optional and requires a [custom lovelace card](https://github.com/thomasloven/lovelace-card-mod) to be installed for extra styling\n3. Put mouse pointer over a file name to see full path to a file and line numbers\n4. To display line numbers in the report just remove `.split(':')[0]` from the card template\n\n\u003cimg src=\"https://raw.githubusercontent.com/dummylabs/thewatchman/main/images/markdown_card_example.png\" width=50%\u003e\n\nThe code for the actions report looks very similar:\n\n```yaml\ntype: markdown\ncontent: \u003e-\n  \u003ch2\u003e \u003cimg src=\"https://brands.home-assistant.io/watchman/icon.png\" alt=\"WM Logo\" width=\"32\" height=\"32\"\u003e Watchman report\u003c/h2\u003e\n  \u003ch3\u003e Missing actions: {{ states.sensor.watchman_missing_actions.state }} \u003c/h3\u003e\n  {%- for item in state_attr(\"sensor.watchman_missing_actions\", \"entities\") %}\n  \u003chr\u003e\u003ctable\u003e\u003ctr\u003e \u003ctd\u003e  \u003cha-icon icon='mdi:cloud-alert'\u003e\u003c/ha-icon\u003e {{ item.id }}\n  \u003ca title=\"{{item.occurrences}}\"\u003e{{item.occurrences.split('/')[-1].split(':')[0]}}\u003c/a\u003e\n  \u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n  {%- endfor %}\ncard_mod:\n  style:\n    ha-markdown:\n      $: |\n        ha-markdown-element:first-of-type hr{\n          border-color: #303030;\n        }\n```\n\n[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=popout\n[forum]: https://community.home-assistant.io/t/watchman-keeps-track-of-missing-entities-and-services-in-your-config-files/390391\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdummylabs%2Fthewatchman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdummylabs%2Fthewatchman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdummylabs%2Fthewatchman/lists"}