> ## Documentation Index
> Fetch the complete documentation index at: https://docs.homiagent.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Context matters

> The better organized your Home Assistant is, the better HomiAgent understands what you ask.

HomiAgent can't see your home. Everything it knows about it comes from Home Assistant: each entity's **name**, the **area** it's in, and **what kind of thing** it is. When you say "turn off the bedroom light", those three pieces of information are how it decides which device to act on.

If your home is well organized, it gets it right the first time. If half your entities are called `Switch 1` and have no area, it has to guess or ask, and every question is one more message for you.

This page covers what's worth tidying up. None of it is required, but it's what improves answers the most.

<Info>
  Anything you change in Home Assistant reaches HomiAgent within seconds. You don't need to restart anything or reconnect the integration.
</Info>

## 1. Use names you'd say out loud

HomiAgent uses the **entity name** as it appears in Home Assistant. It doesn't see the physical device's name or the `entity_id` (unless the entity has no name at all).

Many integrations create generic names like `Switch 1`, `Plug 2`, or `Channel L1`. On a three-gang switch, that's three entities that look identical to the assistant.

| Instead of | Prefer |
| - | - |
| `Switch 1`, `Switch 2`, `Switch 3` | `Main light`, `Spotlights`, `Counter light` |
| `Smart plug` | `Coffee maker` |
| `0x00158d0001a2b3c4 On/Off` | `Table lamp` |
| `Relay 2` | `Garage gate` |

A few tips:

* **Use the name you actually say.** If everyone at home calls it "the couch light", that's the name.
* **Name it after what's plugged in, not the hardware.** A plug that powers the coffee maker is `Coffee maker`, not `Sonoff plug`.
* **Keep names unique within a room.** Two entities called `Light` in the same room force HomiAgent to ask which one you mean. Having a `Main light` in every room is fine: the area tells them apart.

<Steps>
  <Step title="Open the entity">
    In Home Assistant, go to **Settings → Devices & services → Entities** and click the entity.
  </Step>

  <Step title="Open its settings">
    Click the gear icon in the top-right corner of the dialog.
  </Step>

  <Step title="Change the name">
    Edit the **Name** field and save.
  </Step>
</Steps>

<Tip>
  You don't need to change the **Entity ID**. HomiAgent only looks at the name, and changing the ID can break automations and dashboards that already use it.
</Tip>

## 2. Put every device in an area

When you ask for something, HomiAgent first works out **which room** you're talking about, and only then looks for the device inside it. An entity with no area is much harder to find.

You can set the area on the **device** (all its entities inherit it) or directly on the **entity**, if it's somewhere different from the rest of the device. If both are set, the entity's area wins.

<Steps>
  <Step title="Open the device">
    Go to **Settings → Devices & services → Devices** and click the device.
  </Step>

  <Step title="Edit the area">
    Click the pencil icon, pick the **Area**, and save.
  </Step>
</Steps>

A few tips:

* **Name areas the way you talk about them.** "Master bedroom", "Anna's room", "Balcony". HomiAgent understands variations, but the right name helps.
* **Scenes, scripts, and automations don't need an area.** They're found by name.
* **Check the result** on the [**Devices**](https://homiagent.app/app/devices) page of the dashboard. It shows your devices grouped by room, exactly the way HomiAgent sees them.

### Tell it where you are

If you're about to give several commands in the same room, say so once:

> I'm in the office.

From then on, "turn on the light" or "turn on the AC" refers to the office until you move to another room. If you have more than one home connected, HomiAgent remembers a room for each one.

## 3. Say what each thing really is

Not every device is what it looks like. An LED strip wired to a relay shows up in Home Assistant as a **switch**, not a **light**. When you ask to "turn off all the lights", HomiAgent might leave that strip out.

To fix this, HomiAgent automatically creates a set of **labels** in your Home Assistant. Apply the right label to the entity and the assistant treats it as that type, without changing anything else in Home Assistant.

| Label | Use when the entity is... |
| - | - |
| `homi_entityType_light` | a light (LED strip, chandelier, or lamp wired to a relay or plug) |
| `homi_entityType_outlet` | an outlet |
| `homi_entityType_switch` | a regular switch |
| `homi_entityType_fan` | a fan or exhaust fan |
| `homi_entityType_cover` | a curtain, blind, or gate |
| `homi_entityType_lock` | a lock |
| `homi_entityType_valve` | a valve (water, gas, irrigation) |
| `homi_entityType_siren` | a siren or audible alarm |

<Steps>
  <Step title="Open the entity">
    Go to **Settings → Devices & services → Entities** and click the entity.
  </Step>

  <Step title="Add the label">
    Click the gear icon, pick the matching `homi_entityType_...` label in the **Labels** field, and save.
  </Step>
</Steps>

Use **one** type label per entity.

<Warning>
  Avoid Home Assistant's **Show as** option for this. It doesn't just change how the entity looks: it creates a new entity with a different ID and leaves the old one orphaned, which can break automations and dashboards. HomiAgent's labels don't touch any of that.
</Warning>

## 4. Hide what doesn't matter

A typical home has hundreds of entities you'll never ask the assistant about: Wi-Fi signal strength, firmware updates, status LEDs, diagnostic sensors. All they do is give HomiAgent more options to choose from and more chances to get it wrong.

You can hide them in two ways, and both stay in sync:

<Tabs>
  <Tab title="In the HomiAgent dashboard">
    Open the [**Devices**](https://homiagent.app/app/devices) page and uncheck the entities the assistant shouldn't see.
  </Tab>

  <Tab title="In Home Assistant">
    Apply the `homi_ignore` label to the entity, the same way as the type labels above.
  </Tab>
</Tabs>

Hidden entities disappear completely for the assistant: it can't read their state or control them. To bring one back, check it again in the dashboard or remove the label.

<Tip>
  Hiding entities is also a way to stay in control. If you don't want HomiAgent touching the front door lock, hide it.
</Tip>

## Quick checklist

* [ ] The entities you use have names you'd say out loud.
* [ ] No room has two entities with the same name.
* [ ] Every physical device is in an area.
* [ ] Lights wired to relays or plugs have the `homi_entityType_light` label.
* [ ] Diagnostic entities, and anything you don't want exposed, are hidden.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.