Written, of course, with the help of Claude…
The problem
When you’re deep in a flow at midnight adjusting a lux threshold or rewiring a logic branch, you know exactly what you’re doing. Six months later, you don’t. Which flows read the Holiday mode variable? What’s the contract between the heating watchdog and the house state flow?
This gets harder as a setup grows. I have 114 flows and over 230 devices, spanning energy management, security, heating, presence, lighting, climate monitoring, audio, and more. Each area is typically several flows working together — reading shared variables, triggering each other, depending on the same physical devices. Some individual flows are substantial pieces of engineering in their own right: the Sleep routine runs to 193 cards; the SolarEdge watchdog to 166. There’s no way to keep a reliable mental model of all of it. I needed documentation.
Not just a list of flows — structured notes explaining how each area of the system actually works: the triggers, the conditions, the logic branches, the inter-flow dependencies, the devices and variables involved.
Documenting everything with Claude
My documentation lives in NotePlan, a markdown notes app that doubles as a personal knowledge wiki. NotePlan has its own MCP server, which means Claude can read, write, and maintain notes directly — it’s how I manage a lot of structured knowledge, and it became the natural home for Homey documentation too.
For Homey access, most users on Claude will reach for the Athom public MCP server. I’m on a team account that doesn’t allow unapproved cloud MCPs, so I had Claude build me a local Node.js MCP server talking to Homey’s local REST API directly. It exposes tools to fetch flows by ID, list variables, list devices, and list zones — enough for Claude to read and understand the full detail of any flow.
Then I created a documentation skill: a structured prompt that guides Claude through documenting one area of the system at a time. For each area it fetches the relevant flows in full, reads through all the cards and arguments, and produces a structured note covering the system overview, each flow in detail, and a dependencies table listing every variable, device, and third-party app involved. Each note also cross-links to related areas — the security note references the house states note, which references the presence note.
The result is 17 notes plus a hub index, covering: energy management, house states, presence and modes, heating (main house and garden room), audio and announcements, lighting (downstairs, upstairs, occupancy/light level, and outdoor), security, Apple TV and media, system and maintenance, notifications, the workshop, guest network, and climate monitoring.
The new problem: drift
Documentation written once becomes wrong. A lux threshold gets tuned. A timer gets adjusted. A flow gets renamed. A new motion sensor gets added to a zone and three flows quietly start depending on it. You refactor how presence detection works and the variable that six other flows read gets replaced by two new ones. Gradually — sometimes suddenly — the notes drift away from reality. With 114 flows across 17 notes, staying on top of this manually is not realistic.
The documentation is genuinely useful when I’m making changes — I’ll often have the relevant note open while I’m editing flows. But then expecting myself to accurately remember and document every change I just made, every time, was never realistic. I needed a system that would come along after me and do it thoroughly and automatically — which sounded like a job for Homey!
Having already been through the documentation process with Claude, I asked it what would make things more efficient and fully automated. That conversation shaped the key design decisions: how to detect changes cheaply without fetching every flow, how to store enough state to make updates surgical rather than wholesale, and how to keep the whole thing observable. Claude designed the full architecture in chat, building directly on what we’d learned from the documentation skill.
The sync system
This part was built in Claude Code, which also updated the local MCP server with the new tools it needed. The solution has three additional pieces. A Homey SDK v3 companion app runs on the Pro and polls Homey’s internal REST API every five minutes. On each poll, it computes a SHA-256 hash of the full card payload for every flow and diffs it against a stored snapshot — catching changed thresholds, timer durations, announcement strings, and variable references at the individual card level. Everything lands in a rolling changelog persisted in Homey settings.
Two new MCP tools expose this: get_changelog returns structured change entries since a given date; list_flows_metadata returns lightweight snapshots for all flows without pulling full card payloads. Each documentation note now carries YAML frontmatter — flow IDs, per-flow hashes, and a last_synced timestamp — so the system knows the exact baseline state when a note was last verified. The system also maintains a flow manifest in NotePlan: a central index mapping every flow ID to its documentation note, with card counts and hashes tracked for every documented flow.
A sync skill ties it together. When I ask Claude to sync, it reads the changelog since the earliest last_synced across all notes, groups changes by documentation note, and presents a plain-English summary for review before touching anything: “Security states: lux threshold 1000->500. Downstairs Hall lights: new motion sensor trigger added.” I can approve, skip, or defer individual items. The result is documentation that reflects exactly what Homey is actually doing right now — without me having to touch it.
The thoroughness comes from the diff quality. Because the companion app captures the exact card-level change at poll time, Claude isn’t guessing what changed — it knows. That’s what makes it possible to update one sentence in one note without disturbing anything else.
Of course, I’m still tinkering. Next up is automating the sync itself using Cowork scheduled tasks so it runs without me having to prompt it at all. I’m also iterating on the documentation format and adding richer cross-referencing between notes — partly for my own navigation when reading them directly, and partly so that when I’m chatting with Claude about my setup, it can move fluently between related areas without losing context.
