{"id":51853560,"url":"https://github.com/linit01/helmsman","last_synced_at":"2026-07-23T22:01:45.288Z","repository":{"id":370610715,"uuid":"1294246105","full_name":"linit01/helmsman","owner":"linit01","description":"AI-assisted automation auditor and helper for Home Assistant: rules + local-LLM audits, validated one-click fixes with rollback, and plain-language automation drafting via Ollama","archived":false,"fork":false,"pushed_at":"2026-07-09T21:08:23.000Z","size":151,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-09T21:13:22.543Z","etag":null,"topics":["custom-component","hacs","home-assistant","home-automation","llm","ollama"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linit01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-08T21:10:32.000Z","updated_at":"2026-07-09T21:08:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/linit01/helmsman","commit_stats":null,"previous_names":["linit01/helmsman"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/linit01/helmsman","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linit01%2Fhelmsman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linit01%2Fhelmsman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linit01%2Fhelmsman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linit01%2Fhelmsman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linit01","download_url":"https://codeload.github.com/linit01/helmsman/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linit01%2Fhelmsman/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35817929,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-component","hacs","home-assistant","home-automation","llm","ollama"],"created_at":"2026-07-23T22:01:44.545Z","updated_at":"2026-07-23T22:01:45.277Z","avatar_url":"https://github.com/linit01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Helmsman\n\n**AI-assisted automation helper for Home Assistant.** Helmsman audits your existing automations, surfaces problems in its panel with fixes attached, proposes LLM-generated improvements and brand-new automations you can apply with one click — no copy-paste, powered by local Ollama. It even benchmarks your Ollama server's models against your own automations and recommends the best one.\n\n\u003e Part of the Beacon Ecosystem. See `docs/ADR-001` for the architecture decision record.\n\n## Status\n\nAll four planned milestones are implemented; current releases harden them based on real-world use. Writes happen **only** on explicit approval in the panel, always behind a config snapshot, and only to `automations.yaml`.\n\n| Milestone | Scope | Status |\n|-----------|-------|--------|\n| MVP-1 | Collector + rules pass, Repairs issues, findings sensor | Done |\n| MVP-2 | Ollama review pass, schema-validated suggestions (read-only) | Done |\n| MVP-3 | Approval panel, snapshot/apply/rollback | Done |\n| MVP-4 | New-automation creation: describe-it box + proactive suggestions, same validation/approval flow | Done |\n| 0.4.x–0.5.x | Hardening: visible review progress and per-automation outcomes, auto-tuned LLM timeouts from measured model speed, model benchmark with recommendation | Done |\n\nUpdates ship as [GitHub releases](https://github.com/linit01/helmsman/releases); HACS surfaces them as standard update entities in **Settings → Updates**, with the release notes shown in the update dialog.\n\n## Rules\n\n| Rule | Severity | What it catches |\n|------|----------|-----------------|\n| `missing_entity` | Error | References to entities that no longer exist (renamed/removed) |\n| `unavailable_entity` | Warning | References to entities currently unavailable |\n| `unloaded_entity` | Warning | References to entities registered but not loaded — the integration is down or still starting; reload it, don't edit the automation |\n| `deprecated_service_key` | Warning | Legacy `service:` syntax (renamed to `action:` in HA 2024.8) |\n| `deprecated_trigger_platform` | Warning | Legacy trigger `platform:` syntax (renamed in HA 2024.10) |\n| `never_triggered` | Info | Enabled automations that have never fired |\n| `stale_automation` | Info | No trigger within the stale window (default 90 days) |\n| `single_mode_with_waits` | Info | `mode: single` plus delay/wait — re-triggers get dropped |\n\nError and Warning findings appear at the top of the Helmsman panel under **Needs attention**, right next to the tools that fix them (as of 0.9 Helmsman no longer publishes to Settings → Repairs — fixing happens where the fixes live). The full list including info findings is in the panel's Findings table and on `sensor.helmsman_findings`.\n\n## Requirements\n\n| Requirement | Needed for | Notes |\n|-------------|-----------|-------|\n| Home Assistant 2025.1+ | Everything | The in-panel brand icon needs 2026.3+ |\n| [HACS](https://hacs.xyz/docs/use/download/download/) | Installation | Or copy the folder manually (below) |\n| [Ollama](https://ollama.com) server on your LAN | AI features only | Reviews, rewrites, drafts, and the model benchmark |\n\n**Without Ollama, Helmsman still works**: rules-based audits, the panel's Needs attention and Findings sections, the stranded-automation replace/disable tools, and the panel all function with the Ollama URL left blank. The AI features light up the moment you point Helmsman at a server.\n\n### Setting up Ollama (one-time, ~10 minutes)\n\n1. **Install Ollama** on any reasonably powerful machine on your network (a Mac, a gaming PC, a server with a GPU): [ollama.com/download](https://ollama.com/download) has installers for macOS, Windows, and Linux (Linux is a one-line script). Avoid running it on the HA host itself unless that machine has real horsepower.\n2. **Pull a coder-class model** — automation configs are code, so coder models do best. From the [model library](https://ollama.com/library):\n   - `ollama pull qwen2.5-coder:7b` — good starting point, runs in ~8 GB of RAM/VRAM\n   - `ollama pull qwen2.5-coder:14b` — better quality, ~16 GB\n   - Have several pulled? Helmsman's built-in benchmark tests them against your own automations and recommends one.\n3. **Expose Ollama to your network** — by default it listens only on `localhost`, so Home Assistant on another machine cannot reach it. Set `OLLAMA_HOST=0.0.0.0` per the [Ollama FAQ](https://github.com/ollama/ollama/blob/main/docs/faq.md#how-do-i-configure-ollama-server) (systemd override on Linux, `launchctl setenv` on macOS).\n4. **Verify from another machine**: `curl http://\u003collama-host\u003e:11434/api/tags` should return your model list. That same URL (without `/api/tags`) is what you enter in Helmsman's configuration.\n\nAll inference stays on your LAN — no automation data leaves your network.\n\n## Installation\n\n**Install on a test HA instance first.** Helmsman is read-only until you approve a change in the panel, but it is new code touching automation internals.\n\n### HACS (custom repository)\n\n1. HACS → ⋮ (top right) → Custom repositories\n2. Add `https://github.com/linit01/helmsman`, category *Integration*\n3. Back in HACS, search for **Helmsman**, open it → ⋮ → **Download**\n4. Restart Home Assistant when prompted\n5. Settings → Devices \u0026 Services → Add Integration → **Helmsman**\n\n### Manual\n\nCopy `custom_components/helmsman/` into your HA `config/custom_components/` directory and restart.\n\n## Icon\n\nSince Home Assistant 2026.3, custom integrations ship their own brand icons: the gold ship's wheel lives in [`custom_components/helmsman/brand/`](custom_components/helmsman/brand/) (`icon.png` 256×256, `icon@2x.png` 512×512, plus the `helmsman.svg` source) and appears automatically in Devices \u0026 Services — no `home-assistant/brands` PR required. On older HA versions a placeholder is shown; the sidebar panel shows the wheel regardless, as it's embedded in the panel itself.\n\n## Configuration\n\n| Option | Default | Notes |\n|--------|---------|-------|\n| Ollama server URL | *(blank)* | e.g. `http://192.168.1.50:11434` — see [Requirements](#requirements); blank disables the AI features |\n| Ollama model | `qwen2.5-coder:14b` | Any pulled model that handles JSON structured output; use the panel's benchmark to pick |\n| Audit interval | 24 h | 1–168 |\n| Stale threshold | 90 days | 7–365 |\n\n## Usage\n\n- Audits run automatically on the configured interval and once at startup.\n- Run one on demand: **Developer Tools → Actions → `helmsman.run_audit`**.\n- Findings: the panel's **Needs attention** section (errors/warnings) and Findings table, plus `sensor.helmsman_findings` (counts in state, details in attributes).\n- With Ollama configured, automations flagged with errors/warnings are reviewed in the background after each **scheduled** audit (up to 10 per pass). Startup and manual audits (panel button, run_audit service) are rules-only — automatic reviews follow the schedule; start one yourself with Review flagged whenever you like. Proposals appear on `sensor.helmsman_suggestions` — the proposed YAML is in the attributes.\n- Review any single automation on demand: **Developer Tools → Actions → `helmsman.review_automation`** with the automation selected, or leave it empty to review all flagged ones. Reviews run in the background: the panel shows a progress banner (N/M automations), and a **Last review details** table records the outcome for every automation — no changes suggested, rejected by a gate (with the reason), suggestion held, or skipped.\n- **Timeouts are self-tuning.** A quick probe measures the model's real speed (Ollama reports token timings), and each automation's time budget is predicted from its config size at that speed. Automations predicted to take over 10 minutes are skipped with a note quoting the prediction — a faster server or model includes them again automatically. Nothing to configure.\n- **Helmsman panel** (sidebar, admin-only): suggestions as side-by-side diffs with Approve/Dismiss, the findings table, and per-automation snapshots with Roll back. Applying reloads automations immediately.\n- Only automations with an `id` in `automations.yaml` (i.e. everything the UI editor manages) can be applied to; package/include-managed YAML is detected and refused.\n- **New automation** (panel, top section): type what should happen in plain language and hit **Draft it**. The draft — same three validation gates as review suggestions — appears as a card with summary, explanation, and YAML. **Create automation** writes it disabled; enable it from the automations page when ready. Also scriptable via `helmsman.draft_automation`.\n- **Helmsman noticed**: after each audit, a registry scan flags motion sensors that share an area with lights but aren't referenced by any automation. Motion sensors that belong to camera devices are labeled *camera motion* and sorted after standalone sensors — still offered (camera-driven outdoor lighting is a real pattern), just not ahead of dedicated PIRs. **Draft it** feeds the suggested wording through the same draft pipeline; **Dismiss** is remembered permanently.\n- **Stranded automations** (panel): automations referencing entities that no longer exist get a card with three ways forward — pick replacement entities from same-domain dropdowns (applied through snapshot/rollback), **Rewrite with AI** (the model redesigns the automation around currently available entities and the result arrives as a normal diff suggestion), or **Disable** the automation in one click.\n- **Model benchmark** (panel, Model section): Helmsman lists the models on your Ollama server, ranks the plausible candidates (coder-class preferred, embedding/vision models excluded, current model always included), and benchmarks up to four against a sample of your own automations — smallest flagged plus median size. The results table shows measured speed, valid-proposal rate, and average time per automation, badges the recommended winner, and a **Use** button switches models in one click (the integration reloads; results survive). Point the URL at a different Ollama server and re-run to compare hardware the same way.\n\n- **Deterministic fixes, no AI needed**: deprecated-syntax findings (`service:` → `action:`, trigger `platform:` → `trigger:`) are fixed by the rules engine directly — the corrected config appears as a suggestion right after the audit, marked \"deterministic rules — no AI\", validated like everything else, applied through the same approve/snapshot/rollback flow.\n\n### Suggestion gates\n\nA rejected proposal is not the end: Helmsman feeds the exact rejection back to the model and demands a corrected config, up to 3 attempts, before reporting failure. An LLM proposal is discarded (never shown) unless it:\n\n1. Is a complete automation config with triggers and actions.\n2. References only entities that exist (or that the original automation already referenced) — no invented entity IDs.\n3. Passes the same config validation Home Assistant's automation editor uses.\n\nRejections aren't silent: the reason (including HA's validation error text) appears in the panel's Last review details table or the draft error banner. Resolved findings clear from Needs attention automatically on the next audit.\n\n## Development notes\n\n### CI\n\nGitHub Actions runs three jobs on every push and weekly on a schedule: **contract tests** (pytest against both the current Home Assistant release and the beta channel — asserting the internal surfaces Helmsman relies on: config validator call, `raw_config` access, panel registration), **hassfest**, and **HACS validation**. The weekly schedule is the early-warning system: it fails while a breaking HA change is still in beta, before any user updates.\n\n\n- Raw automation configs are read in-process from the automation entity component (`raw_config`) — the same config the built-in automation editor operates on. If that internal surface moves in a future HA release, the collector degrades gracefully to state-based rules only and logs a warning.\n- Rules are pure functions (`rules.py`) with no HA imports; run the unit assertions with plain Python.\n- Entity extraction is conservative (explicit `entity_id`/`entities` keys plus a domain-restricted regex over templates) to keep false positives low.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinit01%2Fhelmsman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinit01%2Fhelmsman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinit01%2Fhelmsman/lists"}