Fanad

Fanad · for Home Assistant

Get it out of your head.

The no-nag scratchpad that lives in your Home Assistant: personal tasks and memories, without turning HA into a full-on LLM assistant.

Private, local-first tasks, notes, lists and timers. A bot in your Telegram for the road, a rich web UI in your sidebar at home. No nagging, no guilt streaks, a pad that empties. DM your house, it can ping you back.

Local · no cloud by default No telemetry aarch64 + amd64 Open source · MIT
Install on Home Assistant See what it does

Why it exists

Built to fill the gaps in my own Home Assistant

I run Home Assistant OS at home. It's brilliant at devices and terrible at remembering things for me. I also wanted remote control without exposing anything to the public internet. So I text a bot on Telegram, remind me to take the bins out at 7, timer 12 min, ha turn off the kitchen lights, and it just works, because Telegram is an outbound connection: no open ports, no reverse proxy, no cloud tunnel. At home, the full web UI. A lightweight local LLM you already run (LM Studio or Ollama) does the parsing and summarizing.

What you get

Timers, tasks, and remote control, from Telegram or your sidebar

⏲️

Server timers

"timer 20 min for the oven" from any phone in the family. The ding announces on your Voice PE or media players, fires a script, or sends a notify.

✅

Tasks & reminders

Natural language in ("call the dentist on tuesday"): deadlines, snooze, one-task-at-a-time focus. Dated tasks push straight to your HA calendar.

🏠

ha from anywhere

"ha turn on porch light", "ha run goodnight" from Telegram, routed to your own Assist agent. Remote control, zero exposed ports.

📝

Notes & nested lists

Packing lists, shopping, project outlines. A pad that empties, not a notes app that fills up. Get it out of your head.

💬

Three surfaces

Telegram and Slack on the road, a rich web UI in your HA sidebar at home. Same data, same brain, everywhere.

🧩

Opt-in modules

Journal with daily/weekly summaries, diet logging, process batches, sub-notebooks, metrics. All off by default. Turn on only what you'll use.

The privacy part

What the LLM does, and deliberately doesn't

The one-sentence version

The LLM only parses and ranks what you typed. It never invents data, and it never acts on your house.

  • Parsing, not agency. House commands (ha …) are handed to your own Assist agent verbatim: deterministic passthrough, not model output. Dings ringing your speakers are plain code you opt into.
  • Local by default. Point Fanad at the LM Studio or Ollama box you already run. A mock provider works with no model at all, so you can try it before wiring anything.
  • Cloud is triple-locked. BYO cloud keys only work behind an explicit LLM_ALLOW_CLOUD flag: off by default, hard-blocked at runtime, hidden in the UI when off.
  • Your data stays put. SQLite on your box, secrets encrypted (AES-256-GCM), no telemetry, no phone-home. Everything lives in /data and rides along in HA backups.

Install

Five minutes on Home Assistant

Fanad ships as a Home Assistant App (add-on), a prebuilt image the Supervisor runs for you. You need HA OS or Supervised (Container/Core users: see plain Docker below).

  1. Add the Fanad repository

    Settings → Add-ons → Add-on store (newer installs: Settings → Apps) → the ⋮ menu → Repositories, and add:

    https://github.com/NTBooks/fanad-ha
    Add via My Home Assistant →

  2. Install & start

    Once the repository is added, Fanad shows up in your add-on store (under "Fanad Add-ons"). Open it, click Install, then Start. It appears in your sidebar via ingress, no ports to open, no reverse proxy. Works on 64-bit Pi (aarch64) and amd64.

  3. Point it at your model

    Open the Web UI → ⚙ Settings, pick LM Studio or Ollama, and enter its address, or start with the mock provider and wire the model later.

    Use a LAN IP, not localhost

    Fanad runs in a container, so localhost is the container, not your desktop. Point it at the model's machine, e.g. http://192.168.1.50:1234/v1. Fanad is light enough for a Pi; the model should live on a real box (the desktop already running LM Studio/Ollama).

Ring the house (already paired)

As an add-on, Fanad reaches Home Assistant through the Supervisor automatically, with no URL or token to paste. Type optin ha to turn the module on, then open Settings → Home Assistant and click Load choices: Fanad reads your real voice satellites, scripts, and notify services so you tick them from a list instead of typing entity IDs. Choose which speakers announce the ding, which script to run, or which phones to notify, then hit Save & test to ring them once and confirm it worked.

Backups & uninstalling

Everything lives in /data, which Home Assistant deletes on uninstall, so back up first. HA's native backups cover it (database and encryption key together).

On your dashboard

What Fanad exposes to Home Assistant

Fanad publishes a read-only summary your Home Assistant can poll as sensors, so its numbers can live on a wall tablet, drive automations, or turn a lamp red when something is overdue.

✅

Tasks at a glance

Open, due today, overdue, cleared today, and captured today, plus the next deadline and reminder as timestamps, whether a task is currently active, and today's mood.

🍎

Modules & metrics

Only for the modules you use: active timer and next fire, calories today vs target and last weight, journal, list, and batch counts, and your own metrics (water, steps, whatever you track).

🔒

Numbers, not your notes

Counts and timestamps only by default; task titles are opt-in. A read-only token can only GET, so it can never post a message or change anything.

To wire it up, mint a read-only token in Settings → Security and point a Home Assistant REST sensor at /api/ha/summary with it. Paste-ready YAML is in the sensor guide. A native integration (todo entities, an Assist conversation agent, push sensors) is on the roadmap.

No Home Assistant?

Run Fanad anywhere

You don't need Home Assistant. Fanad is a plain local app: run it on any machine and use the same web UI, Telegram, and Slack.

One line, on any platform with Node 24+:

npx github:NTBooks/Fanad

That copies Fanad into ./fanad, opens a browser setup wizard, installs everything, builds the UI, and starts the server at http://localhost:8787. Point it at your LM Studio or Ollama box in Settings, or choose the mock provider to try it with no model at all. On Windows with no Node, grab the FanadSetup installer from the releases page; it bundles its own runtime.

Or plain Docker

The same image the add-on uses runs anywhere. Then open http://<host>:8787.

docker run -p 8787:8787 -v fanad:/data ghcr.io/ntbooks/fanad-app:latest

Fair questions

The things you're right to ask

Does it need the cloud?
No. Default is fully local. Cloud API keys exist for people without local-model hardware, and they're behind an explicit opt-in flag that's off by default and hard-blocked at runtime.
Does the AI control my house?
No. The LLM parses your scratchpad text. House commands go through your Assist agent as deterministic passthrough. Fanad never originates house actions except the dings you explicitly configure, and those are plain code, not model output.
Is this AI-generated slop that'll be abandoned in a month?
Fair. The codebase is heavily AI-assisted. That's also why it ships with a versioned migration chain and a changelog, and why my own family runs it every day. Judge the code; it's all open.
Why not just HA todo lists + Assist?
Those are great for "add milk to the list." Fanad is for everything durable about you: the loops in your head, deadlines, journals, the timer your spouse set from Telegram while you're both cooking. HA runs the house; Fanad remembers the humans, and they ring each other.
What happens to my data if I uninstall?
Everything lives in /data, which Home Assistant deletes on uninstall, so back up first. HA's native backups cover it (database and encryption key together).

A note from the maker

This is a one-person project

I built Fanad for myself and my own household, and I'm sharing it because it might help you too. Fair warning: my bandwidth for support and changes is limited. I fix what I run into in my own daily use, but I can't promise feature requests, fast replies, or help debugging your particular setup. It's open source under MIT, so you're welcome to read the code, fork it, and open a pull request. Run it because you like what it already does, not because of what it might someday become.