Quick Start

Five minutes from zero to an AI that knows your house.

Prerequisites

Home Assistant OS or Supervised (the add-on system requires the Supervisor).
An Anthropic account — a Claude Pro or Max subscription is the most economical option, since Claude Code authenticates via OAuth and uses your subscription. An API key works too if you’d rather pay per token (note: usage-limit sensors need the subscription login).
A modern 64-bit HA host (any Pi 4/5, x86 NUC, or generic 64-bit server). Older 32-bit ARM boards (Pi 3 and earlier) aren’t supported — prebuilt images exist for amd64 and aarch64 only.
~1 GB of free RAM beyond what HA itself uses. Fast voice mode keeps pre-warmed workers around (~150–300 MB each, max 3); you can turn it off on tight hosts.

Back up Home Assistant first — somewhere that isn’t this machine

brAIn edits your real configuration: automations, dashboards, helpers, entities. It snapshots files before it changes them and brain undo puts them back — but that is not a backup you can restore from. Settings → System → Backups, then copy it off the device. This is also the first thing the panel’s own first-run screen tells you.

Install it

Add the repository. In Home Assistant: Settings → Add-ons → Add-on Store → ⋮ → Repositories, then paste:
Repository URL
```
https://github.com/bruhautomation/BRUH-HA-Apps
```
Install the add-on. Find brAIn in the store and click Install, then Start when it’s done. The install pulls a prebuilt image from ghcr.io rather than building on your machine — a download, not minutes of SD-card writes, and everyone gets the identical image.
Restart Home Assistant — required on first install so HA loads the brAIn integration: Settings → System → Restart. A persistent notification tells you whenever a restart is needed (first install and add-on version upgrades); add-on restarts within the same version don’t need one.
Set up the integration. After the restart, HA discovers it automatically — accept the prompt in Settings → Devices & Services. This registers the conversation agent, the usage-limit sensors, the learning sensors, the seven brain.* core services, and the 65 Power Tools admin services.
Sign in with Anthropic. Open brAIn in the HA sidebar and complete the sign-in. This is the only login — the terminal, insight generation, voice, and memory consolidation all share it.

Let it learn your home

A fresh install has no cards, on purpose. A generic “Energy” or “Climate” card about a home brAIn has never looked at says nothing useful and costs tokens on every run, forever.

Press “Start learning.” brAIn studies your house one topic at a time — naming and areas, occupancy rhythms, energy, climate, device reliability — and files what it finds in memory. This takes a few minutes and runs in the background; close the panel and come back, it picks up where it left off.
Pick your cards. When the study finishes, brAIn proposes a handful of cards grounded in what it actually found, each with a one-line reason citing the evidence. Tick the ones you want. Nothing generates, and the scheduler stays idle, until you do.
Watch the first run. Cards generate one at a time through a queue (friendly to subscription rate limits), so they fill in over a few minutes.

If your home is too sparse to learn from, brAIn says what’s missing instead of inventing generic cards — add more entities, let history accumulate, and run it again. There is deliberately no canned fallback: cards about a house it can’t read would be noise on every run, and would teach you to ignore the dashboard.

Try it

Switch to the Terminal tab — it opens as a chat — and ask for something you’d otherwise have gone digging for:

Why did the hallway light come on at 3am?
Which of my devices have stopped reporting?
Write me an automation that turns the towel rail on when the shower humidity spikes
Rename the switches in the garage to what they actually control

Or ask from the Insights tab’s Ask box and get a card back instead — same engine, same memory. Keep the ones you like as recurring cards, or drop any of them on a dashboard.

Then look at the Findings tab. The number on it is what brAIn already thinks is broken in your house.

Next steps

Use brAIn as your voice assistant. Go to Settings → Voice Assistants → [your pipeline] and pick brAIn as the conversation agent. Give the agent a name, a model, and (optionally) a personality. By default voice can control everything but can’t run shell commands or read files.
Teach it something. Say “remember that we call the office lamp the beacon” to a voice assistant, or run brain memory add "…" in the terminal. It lands in the same document every other surface reads.
Answer its guesses. When brAIn believes something it can’t confirm, it says so at the top of the Findings tab as a yes/no — everything waiting on your decision in one list. Two taps settle it. binary_sensor.brain_waiting_on_you exists so you can push that to your phone — a guess sitting in a panel nobody has open just expires.
Get findings on your phone. Set findings_notify_service to your notify.mobile_app_* service in the add-on config — one option turns new findings into phone pushes, no automation needed (findings_notify_min_severity decides what’s allowed to ring).
Trigger it from automations. Call brain.run_task with a prompt — it runs in the background and (optionally) notifies you when it’s done.
Tune behaviour. See the Reference for every config option and the full service / sensor / tool list.

Common first-install hiccups

Symptom	Fix
Add-on won’t start	Check the Log tab. Almost always an architecture mismatch — prebuilt images exist for `amd64` and `aarch64` only.
Integration not discovered	You probably skipped step 3. Restart HA, then check Settings → Devices & Services (or add brAIn manually).
Sign-in fails	Verify the HA host can reach `console.anthropic.com`. After updates, you may need to re-authenticate.
The terminal asks for a second login	It shouldn’t — one credential is shared with the CLI both ways. If it does, run `brain doctor`; the auth check names the file it found and the one it expected.
”It can’t see my entities”	Confirm `enable_ha_mcp_server: true`, then run `brain doctor` in the terminal — it drives the MCP server end-to-end and reports any tool that errors.
Learning seems stuck	Study sessions are deliberately long-running (up to `study_timeout_minutes`, default 30). The progress list shows which topic is in flight; the add-on log shows the session. A session that actually fails names its real reason in the log — a timeout says timeout — rather than reporting a generic failure.
Usage-limit sensors stay unavailable	They need an OAuth/subscription login (not an API key). New installs show data once you’ve used Claude; the sensor’s `error` attribute explains why if not.