How I built a self-maintaining Homey documentation system with Claude

Tutorials
41

Thanks for looking into this. I installed v1.0.7, opened the cross-ref index page, performed a search, closed the index page and then let it sit for a while.

Unfortunately the crashes and restarts remain. See the below image of the RAM usage in the past hour that shows the restarts:

IMG_2754
IMG_27541872×1460 115 KB

If there any other info I can share or things I can try that would help troubleshooting?

42

Really enjoyed this thread — great to see so many people pointing Claude at their Homeys. I went a slightly different direction and thought it might be a useful data point.

Instead of an app running on the Homey, I built a small standalone monitor that runs on my Synology NAS (Node + Postgres, all built with Claude Code). It polls the Homey’s local API from the outside, so there’s zero extra load or memory footprint on the Homey itself — which, given the RAM/stability talk further up the thread, turned out to be a nice property. My Homey has had a couple of network drop-offs lately and I didn’t want to add anything to its plate. (And thanks @Peter_Bittner for the auto-channel-lock tip upthread — mine’s dropped off WiFi twice recently, so I’m going to try locking the channel on my UniFi as well.)

Because it’s Postgres-backed it’s less “documentation” and more a living observability layer:

  • Human-readable flow view — parses every card into a when / and / then description, plus the variables, devices, flows and apps each flow touches (all cross-linked).
  • Runtime timeline — a tiny marker card writes a variable when a flow runs, so I can see when flows actually fired, not just what they are. The same timeline logs device/variable changes, system health (memory/CPU/uptime), and — new this week — automatic “Homey was unreachable from X to Y” events.
  • Flow changelog — each refresh it hashes every flow’s cards and, on a change, logs a readable before → after (e.g. “set sunshade to 50% → 70%”). No size limit since it’s just event rows in Postgres, and it normalises out card positions/notes so cosmetic edits don’t create noise.
  • Dead-card detection — flags “unavailable” cards that Homey’s own broken flag misses (bit me with Better Logic and a removed app).
  • 3-phase energy logging from the Energy Dongle, charted over time.
  • Docs also live inside the flows as colour-coded note cards (yellow = what it does, blue = what the scripts do, green = test status), readable right where you edit.

For building/editing flows I use the official Athom MCP (write-capable); Claude Code does the rest.

It’s a personal/custom build rather than a packaged app, so nothing to download — but happy to share the approach or snippets if anyone’s curious. Thanks @Jonathan_Draper for the inspiration — different flavour, same spirit.

43

this looks promising

44

https://community.homey.app/t/how-i-built-a-self-maintaining-homey-documentation-system-with-claude/155308/38?u=peter_bittner

More on this issue. The problem had not gone away completely, and I couldn’t work out why I kept losing the connection to the MCP. Turned out the issue was that I have Homey connected to my Wifi and to Ethernet. Homey then prioritises the Ethernet connection. Try to continually connect to the MCP using the Wifi IP address results in some weird side effects in my router needing me to keep rebooting it. As soon as I changed Claude’s config file to the Ethernet IP address fixed everything. MCP Connection has been solid and my router is also. Not sure if this could have also been causing App issues. It would be interesting to create some diagnostic files while the system had the wrong confit.