HA-CustomComponentMonitor

KO | EN

gitlite — search

#nodejs #javascript #docker #python #java #shell #go #mongodb #npm #php #pocketmine-mp #functional-programming

HA-CustomComponentMonitor

★ 36 Open GitHub ↗

Reports on whether you are using your Home Assistant custom components

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Home Assistant Custom Component Monitor

[![HACS](https://img.shields.io/badge/HACS-Custom-41BDF5?style=flat-square)](https://github.com/hacs/integration)
[![Release](https://img.shields.io/github/v/release/loryanstrant/HA-CustomComponentMonitor?style=flat-square)](https://github.com/loryanstrant/HA-CustomComponentMonitor/releases)
[![Release date](https://img.shields.io/github/release-date/loryanstrant/HA-CustomComponentMonitor?style=flat-square)](https://github.com/loryanstrant/HA-CustomComponentMonitor/releases)
[![Downloads](https://img.shields.io/github/downloads/loryanstrant/HA-CustomComponentMonitor/total?style=flat-square)](https://github.com/loryanstrant/HA-CustomComponentMonitor/releases)
[![License](https://img.shields.io/github/license/loryanstrant/HA-CustomComponentMonitor?style=flat-square)](https://raw.githubusercontent.com/loryanstrant/HA-CustomComponentMonitor/main/LICENSE)
[![Last commit](https://img.shields.io/github/last-commit/loryanstrant/HA-CustomComponentMonitor?style=flat-square)](https://github.com/loryanstrant/HA-CustomComponentMonitor/commits)
[![Stars](https://img.shields.io/github/stars/loryanstrant/HA-CustomComponentMonitor?style=flat-square)](https://github.com/loryanstrant/HA-CustomComponentMonitor/stargazers)

[![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=loryanstrant&repository=HA-CustomComponentMonitor&category=integration)

A Home Assistant custom integration that monitors your HACS installation for unused custom components, themes, and frontend resources — and now also helps you manage HACS updates that need follow-up action.

## Overview

Home Assistant allows the installation of custom components such as dashboards/cards, themes, and integrations via the Home Assistant Community Store (HACS). Many of these are left unused over time, and HACS updates can include release notes, breaking changes, or new features that you want to review later.

**Custom Component Monitor** creates sensors that list all HACS-installed custom components and identifies whether they are actually being used (configured integrations, active themes, referenced frontend resources). It includes a custom Lovelace card to visualise everything at a glance.

From v1.3.0, it also includes the former **HACS Update Action Tracker** functionality under the same `custom_component_monitor` domain. One integration now provides:

- the Custom Component Monitor dashboard card
- the HACS Update Action Tracker dashboard card
- the Recently installed but unused dashboard card
- a persistent `todo.hacs_update_actions` to-do list
- the `custom_component_monitor.update_and_action` service

From v1.10.0, the Update Action Tracker can optionally use AI to **summarise and categorise** each pending update (see [AI update summaries & categories](#ai-update-summaries--categories)).

## Screenshots

### Custom Component Monitor card

The CCM card supports section filtering. Summary totals are calculated from the sections selected in that specific card, so an integrations-only card shows integration totals rather than the global HACS total.

**Integrations only**

**Integrations + themes**

### HACS Update Action Tracker card

Screenshots below are from the original Update Action Tracker repository and show the card, generated to-do item, and to-do item details.

**List of components to update**

**Item added to to-do list**

**To-do item details**

### AI update summaries & categories

When AI categorisation is enabled (v1.10.0+), each pending update gains category badges, and the card offers category filtering and a sort-by-category toggle. Expanding a row shows a one-line AI summary above the release notes.

**Category badges, filter, and sort**

**Expanded row with AI summary**

**Enabling it in the integration options**

### Update selected

When you filter the list (by component type or AI category), the bulk button becomes **"Update selected (N)"** and installs only the visible updates — e.g. filter to **Cards** and update just those, leaving integrations (which need a restart) for later. With no filter active it stays **"Update all (N)"**.

## Features

### Custom Component Monitor

- 🔍 **HACS Discovery**: Scans your HACS repositories for all installed custom components
- 📊 **Usage Analysis**: Determines which custom components are actually being used
  - **Integrations**: Checks `core.config_entries` for configured HACS domains
  - **Themes**: Scans Lovelace dashboard configs and HA theme settings for active themes
  - **Frontend Cards**: Matches `custom:` card types in dashboards against installed HACS plugins
- 🔔 **HACS Update Count**: `sensor.hacs_updates` reports how many HACS components have a pending update — ideal for conditional cards and automations
- 📈 **Long-term Statistics**: from v1.9.0 the count sensors declare `state_class: measurement` and a unit, so History renders them as proper graphs and Home Assistant keeps long-term statistics
- 🃏 **Dashboard Card**: Built-in Lovelace card with collapsible sections (optionally collapsed by default), an icon-based sort toggle, and section filtering
- 🧮 **Section-aware Summary Totals**: Installed, used, and unused counts are calculated from the selected card sections
- 🏷️ **Repository Links**: Direct links to each component's repository
- 📅 **Installation Tracking**: Shows how long each component has been installed
- ⚡ **Real-time Updates**: Hourly scans to reflect configuration changes

### HACS Update Action Tracker

- 📋 **Smart Update Card**: Lists pending HACS integration updates with Skip, Update, and Update & Action buttons
- 🚀 **Update All / Update Selected**: One button to install every pending HACS update — or, when the list is filtered (by component type or AI category), just the visible ones (e.g. update all Cards without touching integrations that need a restart). Also exposed as the `update_all` service with an optional `entity_ids` subset
- 📝 **Expandable Release Notes**: Fetches release notes directly from Home Assistant update entities
- 🔗 **Release Links**: Links to the GitHub release page when provided by the update entity
- 🔄 **Real-time Progress Tracking**: Shows installation progress and disables action buttons during active updates
- ✅ **Todo List Integration**: Update & Action installs the update and creates a to-do item with release notes
- 🤖 **AI Summaries & Categories (optional)**: Use a Home Assistant AI Task entity *or* a Conversation agent to label each pending update (Bug fixes, New features, Documentation, Translations, Breaking changes, Dependencies, Other) and write a one-line summary. Generation runs in the background and only ever touches updates that don't already have a summary
- ✨ **Generate Summaries Button**: A card button (and the `generate_summaries` service) to fill in any missing AI summaries on demand, without waiting for the next hourly scan
- 🏷️ **Category Badges, Filter & Sort**: Filter the card by category and sort by category; badges are text labels (readable without relying on colour)
- 🎨 **Polished UI**: Includes a visual editor for the update card title and matches your Home Assistant theme

## Installation

### HACS (Recommended)

1. Open HACS in your Home Assistant instance
2. Go to **Integrations**
3. Click the three dots menu and select **Custom repositories**
4. Add `https://github.com/loryanstrant/HA-CustomComponentMonitor` as repository
5. Set category to **Integration**
6. Click **Add**
7. Find **Custom Component Monitor** in the integration list and install it
8. Restart Home Assistant
9. Go to **Settings → Devices & services**
10. Click **+ Add Integration** and search for **Custom Component Monitor**
11. Press **Submit** to complete the installation
12. Restart Home Assistant again so both Lovelace cards are copied and registered
13. Force refresh your browser if the cards do not appear immediately

Or replace steps 1–6 with this:

[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=loryanstrant&repository=HA-CustomComponentMonitor&category=integration)

### Manual Installation

1. Download the latest release from the [releases page](https://github.com/loryanstrant/HA-CustomComponentMonitor/releases)
2. Extract the contents
3. Copy the `custom_components/custom_component_monitor` directory to your Home Assistant `custom_components` directory
4. Restart Home Assistant
5. Add the integration via **Settings → Devices & services**
6. Restart Home Assistant again so both card resources are staged and registered

## Entities

The integration creates five sensors and one to-do entity:

| Entity | Description |
|--------|-------------|
| `sensor.hacs_installed_components` | Total count of all HACS-installed components with full metadata |
| `sensor.unused_custom_integrations` | Count and details of unused custom integrations |
| `sensor.unused_custom_themes` | Count and details of unused custom themes |
| `sensor.unused_frontend_resources` | Count and details of unused frontend cards/plugins |
| `sensor.hacs_updates` | Count of HACS-installed components with a pending update, with details of each |
| `todo.hacs_update_actions` | Persistent to-do list for HACS updates installed with follow-up actions |

### Sensor Attributes

Each unused sensor provides:

- `total_components` — total installed in that category
- `used_components` — count of components in active use
- `unused_components` — list of unused items with name, version, repository URL, days installed, and category-specific metadata (domain, card type, theme variants)

The `sensor.hacs_updates` sensor provides:

- `updates` — list of components with a pending update, each with `name`, `type`, `repository`, `current_version`, `available_version`, and `entity_id` (the matching HACS `update.*` entity, when one is known)
- `ai_enabled` — whether AI summaries are switched on and pointed at an entity
- `ai_pending` — how many pending updates are still missing an AI summary
- `ai_in_progress` — `true` while a summary generation run is under way
- `ai_last_error` — the last AI failure message, or `null` when the last run was clean
- `ai_last_run` — timestamp of the last generation run

Because its state is a simple count, you can show a card or trigger an automation only when updates exist — for example with a conditional card on `sensor.hacs_updates` being above `0`, mirroring how you might gate the unused-components card on the unused sensors.

### To-do Entity

The `todo.hacs_update_actions` entity supports:

- creating items manually or via the `update_and_action` service
- updating item status when you've reviewed changes
- deleting items
- viewing descriptions with release notes

Items persist across Home Assistant restarts using local storage.

## Dashboard Cards

The integration automatically registers three Lovelace cards:

| Card type | Purpose |
|-----------|---------|
| `custom:custom-component-monitor-card` | Shows installed/used/unused HACS components by category |
| `custom:update-action-tracker-card` | Shows pending HACS updates with Skip, Update, and Update & Action buttons |
| `custom:recently-installed-unused-card` | Shows HACS components installed within a recent window (default 30 days) that are still unused |

### Custom Component Monitor Card

#### Via UI

1. Edit a dashboard → **Add Card**
2. Search for **Custom Component Monitor**
3. Configure title, sort order, and visible sections

#### Via YAML

```yaml
type: custom:custom-component-monitor-card
title: Custom Component Monitor
```

#### Card Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `title` | string | `Custom Component Monitor` | Card title |
| `sort` | string | `name` | Default sort order: `name` or `days` |
| `sections` | list | `["integrations", "themes", "frontend"]` | Which sections to display |
| `collapsed_by_default` | boolean | `false` | Start with every section collapsed; users can still expand them |

#### Examples

**Show everything (default):**

```yaml
type: custom:custom-component-monitor-card
title: Unused Components
```

**Only unused integrations:**

```yaml
type: custom:custom-component-monitor-card
title: Integrations
sections:
  - integrations
```

**Integrations and themes:**

```yaml
type: custom:custom-component-monitor-card
title: Integrations + Themes
sections:
  - integrations
  - themes
```

**Themes and frontend, sorted by days installed:**

```yaml
type: custom:custom-component-monitor-card
title: Themes & Cards
sort: days
sections:
  - themes
  - frontend
```

**Compact card with all sections collapsed by default:**

```yaml
type: custom:custom-component-monitor-card
title: Unused Components
collapsed_by_default: true
```

#### Card Features

- **Summary bar** showing installed / used / unused counts for the selected sections only
- **Collapsible sections** that remember their open/closed state, with an optional `collapsed_by_default` start state
- **Icon sort toggle** in the header (A→Z for name, calendar for days installed) that keeps the card width stable
- **Section filtering** to show only the categories you care about
- **Repository links** for each unused component
- **Visual config editor** for all options

### HACS Update Action Tracker Card

#### Via UI

1. Edit a dashboard → **Add Card**
2. Search for **HACS Update Action Tracker**
3. Optionally customise the title
4. Save

#### Via YAML

```yaml
type: custom:update-action-tracker-card
title: HACS Update Tracker
```

#### Card Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `title` | string | `HACS Update Tracker` | Card title |
| `default_filter` | string | `all` | Initial component-type filter: `integration`, `card`, `theme`, or `other` |
| `default_category_filter` | string | `all` | Initial AI-category filter (e.g. `Bug fixes`); only applies when AI categorisation is enabled |

#### Card Features

- Lists pending HACS integration updates
- Shows component icon, current version, and available version
- Provides **Skip**, **Update**, and **Update & Action** buttons
- Offers a context-aware bulk button (with a confirmation): **Update all (N)** normally, or **Update selected (N)** when the list is filtered — installing only the visible updates, so you can update no-restart items (Cards/Themes) without touching integrations
- Displays a pending count badge, or **Up to date** when clear
- Fetches and renders release notes with basic Markdown support
- Shows progress while updates are installing
- Filter chips by component type, and (when AI categorisation is enabled) by category, plus a sort-by-category toggle

#### AI summaries & categories

The Update Action Tracker can optionally run each pending update through AI to produce a one-line summary and one or more category tags.

**Enable it** in **Settings → Devices & services → Custom Component Monitor → Configure**:

1. Turn on **Summarise & categorise updates with AI**.
2. Choose an **AI entity** — either an [AI Task](https://www.home-assistant.io/integrations/ai_task/) entity (Home Assistant 2025.7+) **or** a Conversation agent. If one doesn't work for your model, try the other.

Once enabled, a **Generate summaries (N)** button appears on the card whenever any visible update is still missing a summary. It calls [`custom_component_monitor.generate_summaries`](#custom_component_monitorgenerate_summaries) for exactly those updates and fills them in one by one as the model responds.

Notes:

- Categories are drawn from a fixed set: Bug fixes, New features, Documentation, Translations, Breaking changes, Dependencies, Other (an update can have several).
- Generation runs **in the background**, never during startup, so a slow model can't hold up Home Assistant. Each result is saved as it arrives, so a restart part-way through keeps whatever was already generated.
- Results are **cached per repository + target version**, and **only updates without a summary are ever sent to the AI**. A cached summary is never regenerated unless you ask for it with `force`.
- It degrades gracefully: if the AI backend can't return a usable result, the scan still completes and those updates simply show no summary (a warning in the log explains why). Failures are recorded and retried with a growing backoff — 15 minutes, 1 hour, 6 hours, then daily, stopping after 5 attempts. The **Generate summaries** button and `force: true` always retry regardless.
- Compatibility depends on the AI backend. In testing, an AI Task entity worked well with capable models (e.g. qwen) and cloud providers; some self-hosted models work better via a **Conversation agent**. The official OpenAI, Ollama, Anthropic, and Google Generative AI providers are good choices.

### Recently installed but unused card

Surfaces HACS integrations, themes, and frontend cards that were installed within a recent window (default 30 days) and are still unused — the "I installed this and forgot to wire it up" view. It reads the same `sensor.unused_*` entities as the main card and filters each unused list by how long ago the item was installed, so it needs no extra configuration to work.

#### Via UI

1. Edit a dashboard → **Add Card**
2. Search for **Recently installed but unused**
3. Optionally adjust the window (days) and visible sections

#### Via YAML

```yaml
type: custom:recently-installed-unused-card
days_window: 30
```

#### Card Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `title` | string | `Recently installed but unused` | Card title |
| `days_window` | number | `30` | Only show unused items installed within this many days |
| `sections` | list | `["integrations", "themes", "frontend"]` | Which categories to display |

#### Card Features

- Lists only unused items installed within the configured window, newest installs first ("today", "1d ago", …)
- Groups results by Integrations / Themes / Frontend Cards, hiding empty groups
- Shows a count badge, or a friendly "all clear" message when nothing recent is unused
- Repository links and version per item
- Marks estimated install dates with a `~` (see the note below)
- **Visual config editor** for all options

#### How install dates work

HACS doesn't record when you installed anything, and a HACS *update* rewrites the component's
files — so before v1.13.0, install age came from the files on disk and an update reset the clock,
making a component you'd had for years look freshly installed.

From v1.13.0 the integration keeps its own record: the first time it sees a component installed,
that date is written down and **never moves forward again**. An update no longer resets it.

- Anything installed from v1.13.0 onwards gets an **exact** date.
- Anything you already had is **estimated** from the files on disk and shown with a `~`
  (`~14d ago`). Those estimates are the old, imperfect behaviour — they're now labelled rather
  than presented as fact, and they age out of the window on their own.
- Items whose install date can't be determined at all are hidden and counted in the footer.

The footer shows when exact tracking began, and `sensor.hacs_installed_components` carries the
same value as the `install_dates_since` attribute.

## Services

### `custom_component_monitor.scan_now`

Triggers an immediate scan of all HACS-installed custom components.

### `custom_component_monitor.update_and_action`

Installs a HACS update and creates a to-do item to track follow-up actions.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `entity_id` | Yes | The update entity to install, for example `update.my_integration_update` |
| `version` | No | Specific version to install. If omitted, installs the latest version |

The to-do item created includes:

- **Summary**: `{Integration name} updated to {version} ({date})`
- **Description**: Update date, release URL, entity reference, and full release notes when available

Example service call:

```yaml
service: custom_component_monitor.update_and_action
data:
  entity_id: update.my_integration_update
```

### `custom_component_monitor.update_all`

Installs **every** pending HACS update in one call. It walks all `update` entities that are HACS-installed, on, and not already updating, and installs each one.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `create_actions` | No | When `true`, each update is installed via `update_and_action` so a follow-up to-do item is created per component (default `false`) |
| `entity_ids` | No | Only update these update entities. If omitted, every pending HACS update is installed. The card's **Update selected** passes the currently-filtered set here |

Example service call:

```yaml
service: custom_component_monitor.update_all
data:
  create_actions: true
```

### `custom_component_monitor.generate_summaries`

Generates the missing [AI summaries and categories](#ai-summaries--categories) for pending HACS updates. **Only updates that don't already have a summary are sent to the AI**, unless `force` is set — so calling it repeatedly is safe and costs nothing once every update is summarised.

Requires AI summaries to be enabled in the integration options; calling it otherwise raises an error rather than doing nothing silently.

| Parameter | Required | Description |
|-----------|----------|-------------|
| `entity_ids` | No | Only summarise these `update.*` entities. If omitted, every pending update missing a summary is processed. The card's **Generate summaries** button passes the currently-shown set here |
| `force` | No | Regenerate even when a summary already exists, and ignore the retry backoff after previous failures. Costs one AI call per update (default `false`) |
| `max_items` | No | Stop after this many AI calls. Omit for no limit |

The service returns a response with the counts, so an automation can act on the outcome:

```yaml
action: custom_component_monitor.generate_summaries
response_variable: result
# result -> {"generated": 3, "failed": 0, "skipped": 12, "remaining": 0}
```

Example service call:

```yaml
service: custom_component_monitor.generate_summaries
data:
  max_items: 5
```

## Migration from HACS Update Action Tracker

Update Action Tracker functionality is now built into Custom Component Monitor under the `custom_component_monitor` domain.

If you previously used the separate Update Action Tracker integration:

1. Install or update **Custom Component Monitor** to v1.3.0 or later
2. Add the **Custom Component Monitor** integration if it is not already configured
3. Replace old card YAML with:

```yaml
   type: custom:update-action-tracker-card
   title: HACS Update Tracker
   ```

4. Replace service calls from `update_action_tracker.update_and_action` to `custom_component_monitor.update_and_action`
5. Confirm the to-do entity is `todo.hacs_update_actions`
6. Remove the old `update_action_tracker` custom integration once you have migrated dashboard cards and automations

## How Detection Works

### Integrations

Compares HACS-installed integration domains against `core.config_entries`. If a domain has no config entry, it's marked unused.

### Themes

Scans all Lovelace dashboard configurations and the system/user theme settings for theme name references. Includes fuzzy matching to handle naming variations (e.g. `ha-transformers-theme` → `transformers-themes`).

### Frontend Cards

Derives expected `custom:` card type names from HACS plugin JS filenames, then searches all Lovelace dashboards for matching `type: custom:xxx` references. Utility plugins like `card-mod` are special-cased.

### HACS Updates

`sensor.hacs_updates` counts HACS-installed components that have a pending update. A component is treated as having an update when its installed release version differs from the latest available version — or, for components that track a branch instead of releases, when the installed commit differs from the latest commit. The `updates` attribute lists each pending update with its current and available version, so a card or automation can react whenever the count rises above zero.

That comes from HACS's stored repository data, which is a snapshot written periodically and can lag reality in both directions — missing an update HACS has already surfaced, or still listing one you installed hours ago. The scan therefore **reconciles it against the live HACS `update.*` entities**, which are authoritative: an update only the entities know about is added (and can now get an AI summary), and a row the entity says is already installed or skipped is dropped. The card and the sensor consequently always describe the same set of updates.

The update card looks for pending `update.*` entities provided by HACS. For **Update & Action**, it calls Home Assistant's `update.install` service and then creates a persistent item in `todo.hacs_update_actions` with release context and release notes when available.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Development Approach

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

If you encounter any issues, please report them on the [GitHub Issues page](https://github.com/loryanstrant/HA-CustomComponentMonitor/issues).

HA-CustomComponentMonitor

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README