Home Assistant Analysis Platform
Find root causes. Prioritize improvements. Understand your installation.

Home Assistant installations grow over time. Devices are replaced, integrations change, entities become unavailable, and a single underlying problem can surface as hundreds of separate warnings. Raw diagnostics expose the symptoms, but rarely explain where to begin.

HADocs is a local-first Home Assistant Analysis Platform that turns installation data into a clear, evidence-based view of system health. It identifies related symptoms, groups them into likely root causes, measures their impact, and recommends the improvements that matter most.

The result is a practical answer to three questions:

• What is happening? An Executive Summary and intelligent Explorer make the installation understandable.
• Why is it happening? Root Cause Analysis connects related incidents and their evidence.
• What should I fix first? Health Scores, estimated repair effort, and Smart Recommendations establish priority.

• Dashboard Engine — the primary product experience for understanding health, impact, priorities, and progress.
• Root Cause Analysis — consolidates related symptoms into evidence-backed causes.
• Health Score — provides a transparent, normalized measure of current installation health.
• Potential Health Score — shows how prioritized repairs could improve the installation.
• Smart Recommendations — ranks actions using impact, affected devices and entities, expected score gain, and estimated repair time.
• Explorer — reveals relationships across areas, devices, entities, integrations, and findings.
• Knowledge Pack — creates structured local context for optional, user-controlled sharing.
• Device Overrides — lets users refine how specific devices are interpreted.
• HTML and Markdown exports — produces portable reports without making exports the primary interface.
• Local First and Privacy First — keeps analysis and data on infrastructure you control.

Choose the installation method that best fits your environment.

• Home Assistant
• Docker
• Windows

The Dashboard Engine is the primary HADocs experience. It is not a static report or a wrapper around generated HTML; it is the working surface for assessing an installation, investigating findings, and deciding what to do next.

From one interface, you can review:

• Executive Summary
• Health Score and Potential Health Score
• Estimated repair time
• Installation Overview
• Root Cause cards and supporting evidence
• Recommended Actions
• Analysis history
• Explorer and Knowledge Pack shortcuts

The Dashboard connects high-level status with the evidence behind it, so you can move from overview to investigation without losing context.

A long list of individual errors often describes only the visible damage. Fixing those items one at a time can waste effort when they originate from the same offline device, failed integration, or configuration issue.

HADocs groups related symptoms into a smaller set of root causes. Each group connects the likely cause with its affected devices, entities, child incidents, estimated repair time, and potential Health Score gain.

Mobile App devices
3 devices offline
176 affected entities
Estimated repair time: 2 minutes
Potential Health Score gain: +8

In this example, 176 unavailable entities are not treated as 176 independent tasks. HADocs identifies one repair path with measurable impact.

The Health Score is a prioritization tool, not an arbitrary percentage. It summarizes the observed condition of the installation using explainable penalties and gives you a stable way to compare impact, choose work, and track improvement over time.

Health Score v2 considers:

• Active affected entities
• Critical issues, warnings, and maintenance findings
• Root cause complexity
• Installation size
• Disabled entities
• Potential improvement

Disabled entities are not counted as active problems. Penalties are normalized so that large installations are not disadvantaged simply because they contain more entities.

HADocs explains why points were lost and which actions can recover them. The Potential Health Score estimates the outcome of addressing identified root causes, making the score useful for planning rather than merely reporting current state.

Smart Recommendations turn findings into an ordered repair plan. HADocs prioritizes actions by expected value instead of asking you to work through every incident.

Depending on the available evidence, a recommendation can include:

• Likely root cause
• Affected entities and devices
• Child incidents
• Estimated repair time
• Expected Health Score gain

Fix what has the greatest impact first.

Explorer is an analysis tool for understanding how an installation fits together. It provides an intelligent path through areas, devices, entities, integrations, findings, and their relationships—not merely a browser for generated files.

Use Explorer to follow a root cause into its affected devices, inspect entity and integration context, and move between related evidence. This makes unfamiliar or complex installations easier to investigate without flattening them into disconnected lists.

The Knowledge Pack is a structured, locally generated representation of the analysis. It can provide context to an AI assistant or another person, but HADocs never sends it anywhere automatically.

You remain in control:

• The Knowledge Pack is created and stored locally.
• A redacted version is available for safer sharing.
• You decide whether to share either version.
• No automatic upload or external AI call occurs.

output/knowledge/
output/knowledge/redacted/

Each scan creates a local analysis package:

output/
├── index.html
├── index.md
├── 00_executive_dashboard.md
├── 01_root_causes.md
├── 02_incidents.md
├── explorer/
├── knowledge/
├── history/
└── csv/

Available output includes the interactive HTML Dashboard, HTML Explorer, Markdown documentation, Knowledge Pack, redacted Knowledge Pack, CSV exports, and history snapshots.

The generated output/index.html remains available as a portable export. It is not embedded as the main HADocs interface.

HADocs is designed for private, local analysis.

• ✅ Runs locally
• ✅ No telemetry
• ✅ No cloud upload
• ✅ No external AI calls
• ✅ Home Assistant token stored in Windows Credential Manager
• ✅ config.json does not store tokens
• ✅ Redacted Knowledge Pack available

HADocs supports three deployment options. Each uses the same analysis engine and web interface.

The app (formally known as add-on) is the easiest option when HADocs should run directly inside Home Assistant.

1. Open Settings → Apps → Repositories in Home Assistant.

2. Add the HADocs repository:

   https://github.com/SirBlondieDK/HADocs
   

3. Refresh the App Store if HADocs does not appear immediately.

4. Install HADocs.

5. Configure the Home Assistant URL and Long-Lived Access Token.

6. Start HADocs.

7. Open the HADocs web interface.

8. Run your first analysis from Overview.

The Home Assistant App currently uses sirblondiedk/hadocs:dev, the project's preview/development channel. Rebuild or reinstall the app after a new image is published to pull the update.

Persistent app data is stored in the mapped /config, /cache, and /output directories.

Create docker-compose.yml:

services:
  hadocs:
    image: sirblondiedk/hadocs:dev
    container_name: hadocs

    env_file:
      - ./docker/hadocs.env

    environment:
      HADOCS_OUTPUT_DIR: /output

    volumes:
      - ./docker/output:/output
      - ./docker/cache:/cache
      - ./docker/config:/config

    ports:
      - "8099:8099"

    entrypoint: ["python", "-m", "src.hadocs.web.app"]

    restart: unless-stopped

Create the persistent directories:

mkdir -p docker/output docker/cache docker/config

Create docker/hadocs.env with your runtime configuration. Do not commit private tokens.

Start HADocs:

docker compose pull
docker compose up -d

Open:

http://SERVER-IP:8099

View logs:

docker compose logs -f hadocs

Update to the newest published image:

docker compose pull
docker compose up -d --force-recreate

Check status:

docker compose ps

The container should remain Up. Docker starts the HADocs web application rather than the one-shot generate command.

The Windows release does not require a separate Python installation.

1. Download the latest Windows release from GitHub Releases.
2. Extract the ZIP archive.
3. Run HADocs.exe.
4. Enter the Home Assistant URL and Long-Lived Access Token.
5. Start the HADocs web interface or run a scan.
6. Open the local address shown by HADocs.

To run HADocs from source:

git clone https://github.com/SirBlondieDK/HADocs.git
cd HADocs
py -3.14 -m pip install -e .
$env:HADOCS_OUTPUT_DIR = Join-Path (Get-Location) "output"
py -3.14 -m src.hadocs.web.app

The web interface is the primary HADocs user experience. It includes:

• Overview
• Analysis
• Interactive Root Cause evidence
• Explorer
• Device Overrides
• Scan logs
• HTML export

The Analysis page is the interactive view for recommendations, Root Cause evidence, and Health Score details. It reads directly from the HADocs data API, keeping the active interface connected to the current analysis rather than a generated report.

HADocs uses the following paths inside containers:

/config
/cache
/output

Recommended Docker mappings:

./docker/config:/config
./docker/cache:/cache
./docker/output:/output

Keep docker/hadocs.env, tokens, generated private reports, and local override files out of public commits.

• Git
• Python 3.11 or newer; Python 3.14 is recommended and used by the current development commands
• Docker, when building or testing container images
• Access to a Home Assistant installation for end-to-end analysis

git clone https://github.com/SirBlondieDK/HADocs.git
cd HADocs
py -3.14 -m pip install -e .
$env:HADOCS_OUTPUT_DIR = Join-Path (Get-Location) "output"
py -3.14 -m src.hadocs.web.app

Remove-Item Env:HADOCS_OUTPUT_DIR -ErrorAction SilentlyContinue
py -3.14 -m pytest -q

$env:HADOCS_OUTPUT_DIR = Join-Path (Get-Location) "output"
py -3.14 -m src.hadocs.web.app

docker build -t hadocs:local .

docker run --rm -p 8099:8099 \
  --env-file ./docker/hadocs.env \
  -e HADOCS_OUTPUT_DIR=/output \
  -v "$(pwd)/docker/output:/output" \
  -v "$(pwd)/docker/cache:/cache" \
  -v "$(pwd)/docker/config:/config" \
  --entrypoint python \
  hadocs:local \
  -m src.hadocs.web.app

Before submitting changes, run the complete test suite and verify that no credentials, private URLs, generated reports, or local override data are included.

• Local First — data remains on infrastructure you control.
• Privacy First — no telemetry, cloud upload, or external AI calls.
• Evidence Before Assumptions — findings are supported by collected evidence.
• Root Causes Before Symptoms — related incidents are treated as a system, not an error count.
• Explainable Prioritization — scores and recommendations show why work matters.
• One Analysis Engine — Home Assistant, Docker, and Windows deployments use the same core engine.

See ROADMAP.md for the complete roadmap.

Current priorities:

• More precise, evidence-based integration assessments
• Better navigation between root causes, devices, entities, and integrations
• Continued web interface refinement
• Stable releases for the Home Assistant App, Docker, and Windows

Contributions are welcome. Start with CONTRIBUTING.md, keep changes focused, and include tests where appropriate.

Before opening a pull request:

Remove-Item Env:HADOCS_OUTPUT_DIR -ErrorAction SilentlyContinue
py -3.14 -m pytest -q

Do not include tokens, private Home Assistant URLs, private generated reports, or local override data.

HADocs was created by a Home Assistant user to make complex installations easier to understand, troubleshoot, and improve.

If HADocs saves you time, consider giving the project a ⭐ on GitHub.