Homebridge LLM Control

Project page · npm package · Security policy

LLM-powered operations plugin for Homebridge: chat control, health monitoring, watchdog checks, scheduled jobs, and guardrailed self-healing for smart-home infrastructure.

Why it is useful

Day-to-day Homebridge operation often means checking logs, restarting services, watching for failures, and manually controlling accessories. This plugin puts those tasks behind chat commands while keeping risky actions behind explicit configuration, allowlists, cooldowns, and quotas.

At a glance

• Platform: Homebridge plugin written in TypeScript
• Interfaces: Telegram, ntfy, Discord webhooks, Homebridge UI/config
• Automation: scheduled jobs, one-shot actions, watchdog checks, daily monitoring
• Safety model: allowlisted commands, cooldowns, daily action limits, runtime config redaction
• Distribution: npm/Homebridge-compatible package with CI and release workflow

Capabilities

• LLM provider presets (OpenAI + custom OpenAI-compatible endpoint)
• Telegram onboarding + chat control
• ntfy (Quick Setup) two-way chat + notifications
• Discord webhook notifications (outbound)
• Direct control of existing Homebridge accessories (lights/switches/outlets) from chat
• One-shot scheduling ("turn off the lights in 30 minutes")
• Optional scheduled Homebridge restarts + restart notifications
• Daily health monitoring
• Watchdog checks for critical signals
• Guardrailed self-healing commands (allowlist + cooldown + daily quota)
• Chat-managed runtime skills (propose/approve workflow) for safe command expansion
• Config-based and chat-created scheduled automations

Package status

Version 1.4.0 is published on npm. The package follows Homebridge's dynamic platform conventions:

• package name starts with homebridge-
• includes keyword homebridge-plugin
• includes config.schema.json
• declares Homebridge platform metadata in package.json

Installation

npm install -g homebridge-llm-control

Or use Homebridge UI search for homebridge-llm-control.

Configuration

You can configure this plugin either:

• In Homebridge UI plugin settings / config.json, or
• Directly from Telegram for the quickest setup: /setup and /config ...

Example config

Minimal (Telegram only; then configure the LLM via /setup in chat):

{
  "platform": "LLMControl",
  "name": "LLM Control",
  "messaging": {
    "botToken": "123456789:AA...",
    "pairingMode": "first_message"
  }
}

Full example:

{
  "platform": "LLMControl",
  "name": "LLM Control",
  "provider": {
    "preset": "openai",
    "apiKey": "sk-...",
    "model": "gpt-4.1-mini",
    "temperature": 0.2,
    "maxTokens": 600,
    "requestTimeoutMs": 30000
  },
  "messaging": {
    "enabled": true,
    "botToken": "123456789:AA...",
    "pairingMode": "first_message",
    "pollIntervalMs": 2000
  },
  "ntfy": {
    "enabled": false,
    "serverUrl": "https://ntfy.sh",
    "topic": "",
    "subscribeEnabled": true,
    "publishEnabled": true
  },
  "discordWebhook": {
    "enabled": false,
    "webhookUrl": ""
  },
  "homebridgeControl": {
    "enabled": true,
    "includeChildBridges": true,
    "refreshIntervalSeconds": 60
  },
  "operations": {
    "scheduledRestartEnabled": false,
    "restartEveryHours": 12,
    "notifyOnHomebridgeStartup": false,
    "notifyOnHomebridgeRestart": true
  },
  "monitoring": {
    "dailyMonitoringEnabled": true,
    "dailyMonitoringTime": "09:00",
    "timezone": "America/New_York",
    "includeLogs": true,
    "logFilePath": "/var/lib/homebridge/homebridge.log",
    "maxLogLines": 300
  },
  "watchdog": {
    "enabled": true,
    "checkIntervalMinutes": 10,
    "criticalPatterns": ["FATAL", "UnhandledPromiseRejection", "out of memory"],
    "autoTriggerOnCritical": true
  },
  "selfHealing": {
    "enabled": true,
    "maxActionsPerDay": 5,
    "commands": [
      {
        "id": "restart-homebridge",
        "label": "Restart Homebridge",
        "command": "sudo systemctl restart homebridge",
        "cooldownMinutes": 60
      }
    ]
  },
  "automations": [
    {
      "id": "daily-check",
      "name": "Morning Check",
      "scheduleCron": "0 8 * * *",
      "prompt": "Review health and summarize any actions needed.",
      "enabled": true
    }
  ]
}

Telegram onboarding flow

1. Create a bot with BotFather and copy the bot token.
2. Paste the token in plugin settings.
3. Choose a pairing mode:
   • Auto-link first chat (easiest): send any message to your bot and it will link that chat.
   • Secret: set a pairing secret in plugin settings, then send /link <secret> to your bot.
   • Onboarding code: the plugin will accept /start <code> (code is shown in Homebridge logs).
4. Run /setup in Telegram to configure your LLM provider (API key + model) from chat.

Telegram commands

• /status
• /unlink
• /help
• /setup
• /cancel
• /hb (device control help)
• /hb list [query]
• /hb on <query|id|lights|switches|outlets|all>
• /hb off <query|id|lights|switches|outlets|all>
• /hb schedule <duration> <on|off> <query|id|lights|switches|outlets|all>
• /jobs list
• /jobs cancel <jobId>
• /health
• /watchdog
• /ask <question>
• /config (show/set/get/reset runtime settings)
• /skills (list skills)
• /skill (manage runtime skills)
• /commands (alias for skills list)
• /run <commandId> (run an allowed skill/command)
• /automation list
• /automation add <name> | <cron> | <prompt>
• /automation remove <id>
• /automation toggle <id> <on|off>

ntfy quick setup (recommended alternative to Telegram)

1. Enable ntfy in plugin settings.
2. Leave topic blank (plugin will auto-generate a random one).
3. Restart Homebridge.
4. Install the ntfy app (iOS/Android) and subscribe to the topic shown in:
   • /status (Telegram) or
   • Homebridge logs.
5. In the ntfy app, publish a message to the topic (for example: /hb list).

Notes:

• The topic acts like a shared secret. Keep it private.
• The plugin ignores its own outgoing ntfy notifications to avoid loops.

Discord webhook (notifications)

If you want notifications in a Discord channel (but not command input), create a Discord webhook for your channel and paste the webhook URL into discordWebhook.webhookUrl.

Controlling lights and devices

This plugin controls your existing Homebridge accessories directly via Homebridge's local HAP HTTP endpoints (in insecure mode).

Quick start:

1. Configure Telegram and link the chat.
2. In Telegram, run: /hb list
3. Turn something off: /hb off <query> (example: /hb off floor lamp)
4. Schedule an action: /hb schedule 30m off lights

Tip: once your LLM provider is configured, you can also just type: "turn off the lights in 30 minutes".

Troubleshooting

"Why can Homebridge UI control my HomeKit devices, but the plugin can't?"

This plugin controls what Homebridge exposes as accessories (from Homebridge plugins / child bridges / external accessories).

If something is only in the iOS Home app (native HomeKit) and not present as a Homebridge accessory, it will not appear in:

• /hb list
• LLM device list

Fix: add the right Homebridge plugin for that ecosystem (or a HomeKit-controller style plugin), then confirm it shows up in Homebridge UI.

Skills (runtime shell commands)

You can add new safe commands from chat without editing config.json:

• Propose: /skill propose <label> | <command> | <cooldownMinutes?>
• Review: /skill pending
• Approve: /skill approve <proposalId> yes
• Run: /run <skillId>

Notes:

• Skills execute only when selfHealing.enabled is true.
• This is still guardrailed: allowlist, cooldowns, and daily quota apply.

Safety model

• LLM cannot execute arbitrary shell commands.
• LLM can only run skills/command IDs from your allowlist (config commands + approved runtime skills).
• LLM may propose a new skill, but it is always pending until you explicitly approve it with /skill approve ... yes.
• Cooldown and daily action quotas are enforced.

Local development

npm ci
npm run check

The release gate runs linting, strict type-checking, unit tests, the production build, and an npm package dry run. CI repeats it across every declared Node.js major version.

Publishing

npm login
npm publish --access public

After npm publish, the plugin appears in Homebridge search (usually shortly after indexing).

License

MIT