opencode-mqtt-home-assistant

An OpenCode plugin that publishes MQTT messages to Home Assistant when your AI coding sessions become idle (agent finishes responding). Perfect for creating automations based on your OpenCode activity.

Features

• 📡 MQTT Publishing: Sends session status to your MQTT broker
• 🏠 Home Assistant Integration: Auto-discovery creates a sensor entity automatically
• 🔄 Automatic Reconnection: Handles broker disconnections gracefully
• ⚙️ Configurable: All settings via environment variables
• 📝 Structured Logging: Uses OpenCode's logging system

Installation

From npm (Recommended)

Add to your opencode.json:

{
  "plugin": ["opencode-mqtt-home-assistant"]
}

OpenCode will automatically install the package at startup.

From Local Files

1. Create the plugin directory:

   mkdir -p .opencode/plugins

2. Create a plugin file (e.g., .opencode/plugins/mqtt.ts):

   export { OpenCodeMqttPlugin as default } from "opencode-mqtt-home-assistant";

3. Add a package.json in .opencode/:

   {
     "dependencies": {
       "opencode-mqtt-home-assistant": "^1.0.0"
     }
   }

Configuration

Configure via environment variables:

| Variable | Description | Required | Default | |----------|-------------|----------|---------| | OPENCODE_MQTT_HOST | MQTT broker hostname/IP | Yes | - | | OPENCODE_MQTT_PORT | MQTT broker port | No | 1883 | | OPENCODE_MQTT_USERNAME | MQTT username | No | - | | OPENCODE_MQTT_PASSWORD | MQTT password | No | - | | OPENCODE_MQTT_TOPIC | Topic for session status | No | home/opencode/session | | OPENCODE_MQTT_QOS | Quality of Service (0, 1, 2) | No | 1 | | OPENCODE_MQTT_VERBOSE | Enable verbose logging | No | false | | OPENCODE_MQTT_MAX_RECONNECT | Max reconnection attempts | No | 5 | | OPENCODE_MQTT_RECONNECT_DELAY | Reconnect delay (ms) | No | 5000 |

Example Configuration

Linux/macOS (in your .bashrc, .zshrc, or .env):

export OPENCODE_MQTT_HOST="192.168.1.200"
export OPENCODE_MQTT_USERNAME="homeassistant"
export OPENCODE_MQTT_PASSWORD="your_password"
export OPENCODE_MQTT_TOPIC="home/opencode/session"

Windows (PowerShell - temporary, current session only):

$env:OPENCODE_MQTT_HOST = "192.168.1.200"
$env:OPENCODE_MQTT_USERNAME = "homeassistant"
$env:OPENCODE_MQTT_PASSWORD = "your_password"
$env:OPENCODE_MQTT_TOPIC = "home/opencode/session"

Windows (Command Prompt - temporary, current session only):

set OPENCODE_MQTT_HOST=192.168.1.200
set OPENCODE_MQTT_USERNAME=homeassistant
set OPENCODE_MQTT_PASSWORD=your_password
set OPENCODE_MQTT_TOPIC=home/opencode/session

Windows (permanent - via System Settings):

1. Press Win + R, type sysdm.cpl and press Enter
2. Go to the Advanced tab → click Environment Variables
3. Under User variables, click New
4. Add each variable:
   • Variable name: OPENCODE_MQTT_HOST
   • Variable value: 192.168.1.200
5. Repeat for all required variables
6. Click OK to save
7. Restart your terminal for changes to take effect

Windows (permanent - via PowerShell, run as Administrator):

[Environment]::SetEnvironmentVariable("OPENCODE_MQTT_HOST", "192.168.1.200", "User")
[Environment]::SetEnvironmentVariable("OPENCODE_MQTT_USERNAME", "homeassistant", "User")
[Environment]::SetEnvironmentVariable("OPENCODE_MQTT_PASSWORD", "your_password", "User")
[Environment]::SetEnvironmentVariable("OPENCODE_MQTT_TOPIC", "home/opencode/session", "User")

Note: After setting permanent environment variables on Windows, you need to restart your terminal or IDE for the changes to take effect.

Home Assistant Setup

Automatic Discovery

The plugin automatically publishes a Home Assistant MQTT discovery message, creating a sensor entity:

• Entity ID: sensor.opencode_session
• States: idle (agent finished) or active (session started)

No manual configuration needed in Home Assistant!

Manual Configuration (Alternative)

If you prefer manual setup, add this to your configuration.yaml:

sensor:
  - platform: mqtt
    name: "OpenCode Session"
    state_topic: "home/opencode/session"
    icon: mdi:robot

Automation Examples

Notify When Session Complete

automation:
  - alias: "OpenCode Session Complete"
    trigger:
      - platform: state
        entity_id: sensor.opencode_session
        to: "idle"
    action:
      - service: notify.mobile_app_your_phone
        data:
          message: "OpenCode has finished processing"
          title: "AI Session Complete"

Turn On Light When Working

automation:
  - alias: "OpenCode Working Light"
    trigger:
      - platform: state
        entity_id: sensor.opencode_session
        to: "active"
    action:
      - service: light.turn_on
        target:
          entity_id: light.office
        data:
          color_name: blue
          brightness_pct: 100

Track Daily OpenCode Usage

sensor:
  - platform: history_stats
    name: "OpenCode Sessions Today"
    entity_id: sensor.opencode_session
    state: "idle"
    type: count
    start: "{{ now().replace(hour=0, minute=0, second=0) }}"
    end: "{{ now() }}"

How It Works

1. Plugin loads when OpenCode starts
2. Connects to your MQTT broker
3. Publishes discovery message for Home Assistant
4. Listens for OpenCode session events:
   • session.created → publishes "active"
   • session.idle → publishes "idle"
5. Reconnects automatically if the broker disconnects

Troubleshooting

Sensor not appearing in Home Assistant

1. Verify MQTT is working in Home Assistant: Settings → Devices & Services → MQTT → Configure → "Listen to a topic"
2. Listen to homeassistant/sensor/# to see discovery messages
3. Check OpenCode logs for connection errors

Connection refused

1. Verify the broker IP and port
2. Check if MQTT broker is running
3. Verify firewall allows connections on port 1883

Authentication failed

1. Set OPENCODE_MQTT_USERNAME and OPENCODE_MQTT_PASSWORD
2. Check the user has publish permissions on the broker

Enable verbose logging

export OPENCODE_MQTT_VERBOSE=true

This will log all MQTT operations to help diagnose issues.

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Run tests
npm test

License

MIT