HA Frontend Prune

ha-frontend-prune is a static analyzer for Home Assistant frontend custom components, primarily aimed at HACS-heavy setups. It scans Lovelace dashboards/resources, compares them against installed frontend candidates, and reports likely uninstall candidates with confidence levels.

Quick Start

go build -o ha-frontend-prune ./cmd/ha-frontend-prune
./ha-frontend-prune -config /config -color auto

Using make:

make build
make test
make deploy HOST=homeassistant.local

What It Scans

• /config/ui-lovelace.yaml
• /config/lovelace/**/*.yaml
• /config/.storage/lovelace*
• /config/.storage/lovelace_resources
• Installed inventory:
  • /config/www/community/*
  • /config/www/hacsfiles/*
  • /config/custom_components/* (domains with frontend hints like www/ or frontend manifest keys)
• HACS metadata hints from /config/.storage/hacs*

Alias Config Workflow

Default file:

• /config/.ha-frontend-prune-aliases.json

On each run (unless disabled), unknown entries are appended so you can map aliases manually.

{
  "version": 1,
  "custom_type_to_repo": {
    "button-card": "button-card",
    "mushroom-template-card": "mushroom",
    "my-integration-card": "my_custom_integration"
  },
  "resource_repo_to_installed": {
    "lovelace-card-mod": "card-mod"
  },
  "unknown_custom_types": [
    "my-weird-card"
  ],
  "unknown_resource_repos": [
    "old-repo-name"
  ],
  "installed_components": [
    "button-card",
    "my_custom_integration"
  ]
}

• custom_type_to_repo can map to community folder names or integration domains.
• resource_repo_to_installed maps resource URL repo segments to installed component names.

Output Categories

• HIGH: no Lovelace resource URL, no matched custom:*, no auxiliary refs.
• MEDIUM: resource exists but no mapped custom:* usage found.
• LOW: weak evidence or integration-backed candidate; verify before uninstalling.

Usage Reporting

• component_usage: all custom types, least-used first.
• low_use_components: custom types with usage count <= low-use-threshold.
• Low-use text output includes dashboard hints and file:line locations so you can quickly refactor.

CLI Examples

# Text report
./ha-frontend-prune -config /config

# JSON report
./ha-frontend-prune -config /config -json

# Custom alias file
./ha-frontend-prune -config /config -aliases /config/my-card-aliases.json

# Disable alias writes
./ha-frontend-prune -config /config -write-aliases=false

# Mark cards with <=3 uses as low-use
./ha-frontend-prune -config /config -low-use-threshold 3

# Color mode: auto | always | never
./ha-frontend-prune -config /config -color always

Quick Deploy to Home Assistant over SSH

Use the helper script:

./cmd/ha-frontend-prune/run.sh --host homeassistant.local

The script cross-compiles for Linux and supports amd64, arm64, and armv7 (Raspberry Pi). By default it auto-detects the remote arch with SSH.

Example overrides:

./cmd/ha-frontend-prune/run.sh --host 192.168.1.10 --user root --arch arm64
./cmd/ha-frontend-prune/run.sh --host ha.local --remote-dir /root --config /config

Safety and Privacy

• This tool is static analysis and heuristic-based; review findings before uninstalling anything.
• It reads files from your Home Assistant config path only.
• It does not make network calls or send your configuration data externally.

Development

go test ./...
go build -o ha-frontend-prune ./cmd/ha-frontend-prune

Or use:

make test
make build

CI runs on GitHub Actions for pushes and pull requests.

License

MIT. See LICENSE.