[opensourcedex]

home-assistant-global-health-score is a free, open source internet of things (iot) project written in Python and released under Apache-2.0. It has 521 GitHub stars, 14 forks and 3 open issues, and was last pushed 37 hours ago. On this registry it ranks #105 of 106 tracked projects in Internet of Things (IoT), with 5 head-to-head comparisons available.

What is home-assistant-global-health-score?

home-assistant-global-health-score (HAGHS) is a fully local, open-source scoring framework that grades a Home Assistant instance from 0 to 100, built for home-automation owners and administrators who want an objective, inspectable reading of how healthy their installation actually is.

What it is

HAGHS is a Python integration for Home Assistant, installable through HACS, that computes a single Health Score between 0 and 100 for a Home Assistant instance. The project describes itself as "the open standard for Home Assistant instance health monitoring" and is licensed under Apache-2.0. Every piece of scoring logic sits in the codebase: the README states plainly that there are no hidden penalties and no black boxes, so an operator can trace exactly why an instance scored the way it did. The score is composed of two weighted pillars, Hardware Performance at 40% and Application Hygiene at 60%.

The problem it solves is the absence of a unified stability metric. As Home Assistant matures into a mission-critical Smart Home OS, an owner is left to form a subjective, ad-hoc impression of whether the installation is well maintained. HAGHS replaces that judgement with a published, reproducible score, and its central design distinction is between transient hardware load and chronic maintenance neglect — the difference between a busy afternoon and a setup that has been quietly drifting for months. The project sets out a short-term mission of becoming the community standard for instance health monitoring and a long-term ambition of being proposed as a native Home Assistant Core feature, with consented metrics helping the Home Assistant project understand how healthy instances are across the ecosystem.

Key capabilities

  • Computes an objective Health Score on a 0–100 scale entirely locally, without sending instance data to a hosted service.
  • Splits the score into two explicit pillars, Hardware Performance (40%) and Application Hygiene (60%), so load and hygiene are weighed separately.
  • Keeps all scoring logic visible in the source, with no hidden penalties or black-box adjustments.
  • Provides label-based "Smart Whitelisting" configuration alongside dynamic exclusions, pattern-based ignore rules, and stale reporting, documented in docs/configuration.md.
  • Supports external databases as part of its configuration options.
  • Exposes the score and its component detail through sensor attributes.
  • Ships a roadmap that includes UI integration as a planned step beyond the sensor-level interface.

Who uses it and how

  • Home Assistant operators who install the integration through HACS, where it is listed in the default marketplace, and track the score over time as a maintenance signal.
  • Households running large, long-lived installations where chronic neglect is harder to spot than a transient load spike and needs to be separated from it.
  • Administrators who want to verify the calculation themselves, since the Apache-2.0 licence and visible scoring logic permit inspection and modification.
  • Privacy-conscious users can rely on the local computation and take part in the opt-in analytics only by consent; those analytics feed the install count shown in the project's badge.
  • The project has been covered by How-To Geek and XDA Developers and discussed on the SmartHütte and HomeTech.fm podcasts and in German-language videos from Simon42 and Tristans Smartes Heim.

Getting started

Install the integration through HACS from the default marketplace and follow the "Installation & Setup" section of the README; further documentation and project information are available at hapulse.dev.

How it compares

No comparable or competing tools are named in the facts supplied for this listing, and no set of paid products is identified as being replaced. Within this registry it stands alone as a health-scoring framework for Home Assistant instances.

When to use it — and when not to

It is a good fit for someone already running Home Assistant who wants a repeatable number to watch and an auditable explanation of what drives it. It is not the right choice for anyone outside the Home Assistant ecosystem, for setups that exclude custom integrations installed through HACS, or for operators who will not accept third-party code in their home-automation stack — though the local-only scoring and Apache-2.0 licence make that code inspectable. The README excerpt available here is partial and the roadmap items, including UI integration, remain planned rather than delivered, so the sensor-level interface is what a user should expect today.

project readme (upstream, from github) — read inline

HAGHS, a health score for your Home Assistant

The open standard for Home Assistant instance health monitoring.

Marketplace | HACS – Default GitHub Release Installs (opt-in analytics) GitHub Stars Buy Me a Coffee AI-Assisted

Quality gate status

Abstract

As Home Assistant matures into a mission-critical Smart Home OS, the need for a unified stability metric becomes paramount. HAGHS is a fully local, open-scoring framework designed to provide an objective Health Score (0-100). It differentiates between transient hardware load and chronic maintenance neglect, providing users with a "North Star" for instance optimization. All scoring logic is fully visible in the codebase, no hidden penalties, no black boxes.

Mission

  • Short-term: Establish HAGHS as the community standard for Home Assistant instance health monitoring.
  • Long-term: Propose HAGHS as a native HA Core feature, bringing unified health scoring to every Home Assistant installation by default. With user consent, HAGHS metrics should help the Home Assistant project understand how the software is being used and how healthy instances are across the ecosystem.

Featured In

Table of Contents

Detailed documentation

The HAGHS Standard

The index is calculated via a weighted average of two core pillars, prioritizing long-term software hygiene over temporary hardware fluctuations.

The Global Formula

$$Score_{Global} = \lfloor (Score_{Hardware} \cdot 0.4) + (Score_{Application} \cdot 0.6) \rfloor$$

Note: We use Floor Rounding (Integer) to ensure a "Perfect 100" is only achieved by truly optimized systems. A penalty drops the score below 100 unless the Config-Audit bonus offsets it in the application pillar; zombies, open repairs and overdue watched entities always cap the application score at 99.

Pillar 1: Hardware Performance (40%)

Short version. Every threshold, tier table and the component rules are in docs/scoring.md.

The hardware score is the average of the measured components: CPU, RAM, I/O (when the kernel provides it) and Disk.

  • Metric source: HAGHS reads Pressure Stall Information (PSI) from the Linux kernel where available and falls back to the CPU and RAM sensors you select. PSI measures stall time, classic sensors measure utilization, so each source has its own threshold tiers.
  • Storage: disk usage is detected automatically, with thresholds per storage type (SD card and eMMC by free GB, SSD by free percent).
  • Power: a reported Raspberry Pi under-voltage costs a flat 20 points.

All hardware details →

Pillar 2: Application Hygiene (60%)

Short version. Every rule, cap and exception is in docs/scoring.md.

Measures "maintenance debt". Every missing point prints a recommendation line and sets a matching rec_* flag.

Factor Points Rule
Zombie entities up to −20, caps at 99 Entities unavailable or unknown past the grace period (5 min, battery 60 min), scaled by their share. An availability signal, not a deletion list.
Updates and Core age −5 per update, −20 Core lag, at most −35 An update counts after HAGHS has seen that version pending for 7 days, also across restarts.
Integration health −5 per entry, at most −15 Config entries stuck in setup error, setup retry or failed unload.
Repairs −5 each, at most −10, caps at 99 Open repairs of other integrations; Home Assistant's "Ignore" takes one out.
Watched entities −5 each, at most −10, caps at 99 Opt-in: entities labelled directly with a stale watch label that have not reported for longer than the stale threshold (default 24 h).
Database −10, or −30 Above 1000 MB + 2.5 MB × entities, or above 2.5 times that limit.
Backup −30 Stale backup: binary_sensor.backups_stale of the Google Drive Backup add-on is on. Without the add-on no backup check.
Config audit up to +10 Recorder keeps at most 10 days (+5); user-set entity filter (+5).
Dead and empty devices none Informational: devices whose monitored entities are all unavailable, or that have no entity.

All application rules →

Configuration

Short version. Every option, the integration-entry exclusion and the external database setup are in docs/configuration.md.

HAGHS is installed via the Marketplace (Home Assistant 2026.11 and later) or HACS (up to 2026.10) and configured via the UI.

1. Prerequisites

Where the Linux kernel provides PSI, nothing is needed. Otherwise add the built-in System Monitor integration and enable its processor and memory usage entities (disabled by default). Database size and disk usage are detected automatically.

2. Installation & Setup

  1. Home Assistant 2026.11 and later: open Settings > Marketplace, search for HAGHS and select Install; the setup opens right away, no restart needed (continue with step 3). Up to 2026.10: download HAGHS in HACS and Restart Home Assistant.
  2. Go to Settings > Devices & Services > Integrations > Add Integration and search for HAGHS.
  3. Follow the setup mask: CPU and RAM sensors (only used without PSI), storage type, ignore labels and patterns, optionally a database size sensor for an external database.

Change any of it later in Settings > Devices & Services > Integrations > HAGHS > Configure; changes apply immediately, no restart required.

All configuration options →

Label Configuration (Smart Whitelisting)

Short version. Label tips, conditional ignore labels, automations, pattern-based ignore and stale reporting are in docs/configuration.md.

Three ways keep an entity out of the score:

  1. Disable the entity; disabled entities never count.
  2. Apply an ignore label to an area, device, entity or update entity. The haghs_ignore label is created during setup; list further labels in HAGHS > Configure > Ignore labels.
  3. Use a glob pattern for entities without a unique ID, which cannot carry a label.

All label options →

Sensor Attributes

Short version. The full list of all attributes with types and meaning is in docs/attributes.md.

The most used attributes for dashboard cards, automations, and templates:

Attribute Type Description
hardware_score int Hardware pillar score (0–100).
application_score int Application pillar score (0–100).
recommendations string Advisor lines naming what costs points or needs a look, or a healthy message.
zombie_count int Total number of zombie entities.
zombie_entities list Entity IDs of zombies, at most 100.
zombie_reasons dict Why each listed zombie is reported; only config_entry_missing strongly points to an orphaned entity.
pending_updates list Names of pending updates, listed at once and counted after 7 days.
repair_count int Number of open repair issues counted toward the score.
integration_unhealthy_count int Number of config entries stuck in setup error, setup retry or failed unload.
db_size_mb float Current database size in MB.
psi_available bool True when PSI provides both CPU and memory data.
cpu_ram_source str/null Where CPU and RAM come from: psi, sensors, partial or none.
stale_watch_count int Number of overdue watched entities.

All attributes →

Roadmap

Planned features, declined items, and completed milestones live in ROADMAP.md. The roadmap follows the HAGHS philosophy: local-only, system-health focus, HA Core compatibility.

UI Integration

Short version. Installation, entity ID and the Lite vs. Pro comparison are in docs/cards.md.

HAGHS provides all data as sensor attributes; two ready-to-use dashboard cards show them. Both are wired to sensor.system_ha_global_health_score.

HAGHS Lite v1.4 (Quick Check): a compact card for a fast overview, score, sub-scores, and actionable links. Configuration: docs/cards/lite.yaml.

HAGHS Lite v1.4 dashboard card

HAGHS Pro v1.4 (Command Center): a comprehensive dashboard with full score breakdown, grouped zombies, database monitoring, recorder health, and deep-links. Configuration: docs/cards/pro.yaml.

HAGHS Pro v1.4 dashboard card

All card details →

FAQ

Short version. All questions and full answers are in docs/faq.md.

Why is my score so low? Check the Advisor recommendations in the dashboard card. They tell you exactly where penalties come from (e.g., "5 update(s) pending", "Stale backup detected").

Can I delete all zombie entities? No, not without checking them. A zombie only means that the entity has been unavailable or unknown for longer than the grace period. Check its integration, device and config entry first; zombie_reasons tells you why each one is listed.

Why did my score change after an update? The release summaries list the behavior changes per release. The recommendations and rec_* flags show which factors cost points right now.

Does HAGHS send any data to external servers? No. All data collection is strictly local. No outbound network traffic is ever initiated by this integration.

How does PSI work and why does HAGHS use it? PSI (Pressure Stall Information) is a Linux kernel feature that measures how long tasks wait for CPU, memory, or I/O, rather than how busy a resource is. HAGHS uses it where available and falls back to classic utilization sensors otherwise.

All questions →

Changelog

Short version. A summary of every release is in docs/changelog.md.

Every change in detail: v2.4.0_CHANGELOG.md (active changelog) and v2.3_CHANGELOG.md (all changes up to v2.3.0).

All release summaries →

AI Disclosure: While the architectural concept and logic are my own, I utilized AI to assist with code optimization and documentation formatting.

Frequently asked questions

Is home-assistant-global-health-score free to use?

home-assistant-global-health-score is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does home-assistant-global-health-score do?

The open standard for Home Assistant instance health monitoring.

What is home-assistant-global-health-score written in?

home-assistant-global-health-score is primarily written in Python. Its source is publicly available at https://github.com/HA-Pulse/home-assistant-global-health-score, and it has 521 GitHub stars.