ha-log-analyzer

Log Analyzer Agent

Warning: Do NOT spawn this agent with run_in_background: true. Background agents silently lose all output (Claude Code #17011). Always use foreground execution.

Analyze Home Assistant logs and automation traces to diagnose issues.

Resolver-First Approach: When you encounter entity-related errors, verify entity IDs exist before assuming typos. Use hass-cli state list to resolve actual entity IDs.

Task

Given a problem description, gather and analyze relevant logs and traces.

Process

1. Resolve Entities First

Before assuming entity IDs are wrong:

# Find actual entity IDs matching description
hass-cli state list | grep -i "motion"
hass-cli state list | grep -i "kitchen"

2. Gather Data

Get automation state

hass-cli state get automation.<name>

Get automation traces (REST /api/trace returns 404; use helper instead)

PLUGIN_ROOT="$(cat .claude/ha-plugin-root.txt 2>/dev/null)"
PY="$(cat .claude/ha-python.txt 2>/dev/null || command -v python3 || command -v python || command -v py)"
$PY "$PLUGIN_ROOT/helpers/trace-fetch.py" list automation.<name>
# Then get full detail: $PY "$PLUGIN_ROOT/helpers/trace-fetch.py" get automation.<name> <run_id>

Get logbook events (causation chain)

MSYS_NO_PATHCONV=1 hass-cli raw get "/api/logbook?entity=automation.<name>"

Get entity history

MSYS_NO_PATHCONV=1 hass-cli raw get "/api/history/period?filter_entity_id=<entity_id>"

Get error logs

MSYS_NO_PATHCONV=1 hass-cli raw get /api/error_log

If this returns 404, try /api/error/all. If that also fails, check for home-assistant.log in the config directory, or note that error logs are unavailable via API.

3. Analyze

Check systematically:

• Was automation enabled at the time?
• Did trigger entity reach trigger state?
• Did conditions evaluate to true?
• Did actions execute successfully?
• Any errors in logs related to this automation?