HA Forensic Lab

Runtime incidents are spread across several Home Assistant views.

History tells you that a state changed. The logbook shows surrounding activity. Automation traces are useful once you already know which automation to inspect. During an unexpected incident, the harder question is how those fragments relate around one concrete change.

HA Forensic Lab starts from that question: this entity changed — what runtime evidence was captured around it?

Capture, inspect, freeze the incident, then export the evidence.

The current pre-alpha records normalized state changes, service calls, automation triggers and script starts into a bounded local buffer. The timeline can be filtered by exact entity ID or event kind, and selecting an event opens its recorded details alongside a plain-language evidence summary.

An incident window can be previewed around the selected event before it is saved. Saved incidents remain available after the rolling buffer moves on, and a sanitized ZIP export can be generated with a SHA-256 checksum for review or a bug report.

Recorder diagnostics stay separate from the investigation timeline so capture/storage health does not get confused with the event sequence being examined.

Context links are evidence. Timing alone is not causality.

Parent-context relationships and structural trace evidence can connect captured events. Events that merely happen near one another remain ordered observations, not invented cause-and-effect links.

A single event with no captured structural link says Cause not captured. Missing evidence remains a gap instead of being filled by a heuristic or an AI root-cause claim.

Bounded local storage with a deliberately narrow export surface.

The rolling buffer defaults to 2,048 events and can be configured from 256 to 8,192. Saved incidents use separate storage with explicit limits, while capture filters do not rewrite incidents that were already frozen.

The panel and WebSocket API are administrator-only. Local records omit raw event payloads, complete service data and trace variables. Export removes user IDs and absolute timestamps, pseudonymizes identifiers and redacts free text while preserving relative timing and execution structure.

An investigation tool, not another monitoring platform.

HA Forensic Lab does not replace Recorder, collect host telemetry, modify automations or promise a complete causal history when Home Assistant did not expose the necessary evidence.

The repository is still pre-alpha and has no numbered public release. The investigation flow exists and can be tested, but the release checklist and compatibility work are intentionally separate from that claim.

Static dependencies answer the question before runtime evidence exists.

Test the current build, inspect the architecture, or read the source.

The repository follows the HACS custom-integration layout. The README documents the current test installation and the technical documentation keeps capture, causality, incident storage, export and WebSocket behaviour versioned with the code.