homebridge-llm-control

LLM-powered operations plugin for Homebridge with:

• 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

Homebridge Store readiness

This package is Homebridge store compatible when published to npm:

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

Installation

After publishing:

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 (recommended for “dirt simple” 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".

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 install
npm run lint
npm run build

Publish to npm/Homebridge store

npm login
npm publish --access public

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

License

MIT