home-assistant

Files (13)

• SKILL.md
• ha_call_service.py · scripts/
• ha_get_automations.py · scripts/
• ha_get_config.py · scripts/
• ha_get_config_entries.py · scripts/
• ha_get_entities.py · scripts/
• ha_get_services.py · scripts/
• ha_get_state.py · scripts/
• ha_get_trace.py · scripts/
• ha_list_traces.py · scripts/
• ha_search_dashboards.py · scripts/
• ha_search_similar_entities.py · scripts/
• ha_trace_summary.py · scripts/

SKILL.md (first lines)

# Home Assistant Helper

## Overview

This skill provides tools and workflows for working with Home Assistant installations. It enables querying the live HA instance for entities, services, and configuration data, debugging automations, and generating YAML configurations for automations and dashboards.

**Key Capabilities:**
- Query entities, states, and services from the live HA installation
- Search for similar entities to use as examples
- Check automation states and execution history
- Generate YAML configurations for copy/paste into HA
- Find real examples from the user's setup to inform new configurations

## Core Workflow

When helping with Home Assistant tasks, follow this general approach:

1. **Understand the requirement** - What is the user trying to accomplish?
2. **Discover existing entities** - Use scripts to find relevant entities in their setup
3. **Find similar examples** - Search for existing automations or entities that do something similar
4. **Generate YAML** - Create well-formed YAML that can be copied directly into HA
5. **Explain the configuration** - Describe what the YAML does and how to install it

## Available Scripts

All scripts require the `HA_TOKEN` environment variable to be set, which contains the Home Assistant long-lived access token. The HA instance is available at `http://homeassistant.local:8123`.

**Important:** All scripts now use `uv` with inline PEP 723 dependency declarations and the `homeassistant-api` library for consistent, maintainable code. Dependencies are automatically installed by `uv` on first run.

### Entity Discovery

#### `ha_get_entities.py [domain]`
Retrieve all entities, optionally filtered by domain.

**Usage:**
```bash
uv run scripts/ha_get_entities.py           # All entities
uv run scripts/ha_get_entities.py light     # Just lights
uv run scripts/ha_get_entities.py sensor    # Just sensors
```

**When to use:** To discover what entities are available, especially when building new automations.

#### `ha_get_state.py <entity_id>`
Get the current state and attributes of a specific entity.

**Usage:**
```bash
uv run scripts/ha_get_state.py light.living_room
```

**When to use:** To check current state, available attributes, or confirm an entity exists.

#### `ha_search_similar_entities.py <pattern>`
Search for entities matching a pattern in their entity_id or friendly_name.

**Usage:**
```bash
uv run scripts/ha_search_similar_entities.py "bedroom"
uv run scripts/ha_search_similar_entities.py "motion"
uv run scripts/ha_search_similar_entities.py "temperature"
```

**When to use:** To find entities related to what the user wants to automate. This is especially useful for finding examples before creating new automations.

### Automation Management

#### `ha_get_automations.py [search_term]`
Retrieve all automations, optionally filtered by search term.

**Usage:**
```bash
uv run scripts/ha_get_automations.py              # All automations
uv run scripts/ha_get_automations.py motion       # Automations with 'motion'
uv run scripts/ha_get_automations.py light        # Automations with 'light'
```

**When to use:** To find existing automations that are similar to what the user wants to create. Use these as templates.

### Automation Trace Analysis

#### `ha_list_traces.py [automation_id]`
List automation execution traces with timestamps and status.

**Usage:**
```bash
uv run scripts/ha_list_traces.py                    # All traces
uv run scripts/ha_list_traces.py 1761430536701      # Specific automation traces (using numeric ID)
```

**Important:** Use the numeric automation ID (e.g., `1761430536701`), not the full entity_id (e.g., `automation.bedroom_light`). You can find the numeric ID in the automation's attributes from `ha_get_automations.py` output.

**When to use:** To see recent automation runs, their status, and timing. Use this to identify which run IDs to investigate further.

**Output includes:**
- Run ID (for use with `ha_get_trace.py`)
- Timestamp
- Execution state (stopped, running, etc.)
- Script execution status (finished, failed_single, failed_conditions, etc.)
- Last step executed
- Any errors

#### `ha_get_trace.py <automation_id> <run_id>`
Get detailed step-by-step trace for a specific automation run.

**Usage:**
```bash
uv run scripts/ha_get_trace.py 1761430536701 1ceef6b2b6f63a8745eb5dba3fe12f71
```

**Important:** Use the numeric automation ID (e.g., `1761430536701`), not the full entity_id.

**When to use:** To debug a specific automation run. Shows the complete execution path including:
- Trigger details
- Condition evaluations (pass/fail)
- Actions executed
- Variables at each step
- Timing information
- Error details if failed

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding