Control OpenCode with Home Assistant actionable notifications

Share your Projects!
, ,
1

What is this?

opencode-homeassistant is a plugin for OpenCode, a terminal-based AI coding assistant (think Cursor, but in your terminal). The plugin sends the agent’s status to Home Assistant via a webhook every time the state changes — so you can build automations around your AI coding workflow. It optionally lets you respond to permission requests from HA.

States

The plugin reports four states:

State When
busy Agent starts processing a task
idle Agent finishes and is waiting for input
waiting Agent needs your attention (permission prompt or question)
error Session encountered an error

Webhook payload

{
  "state": "busy",
  "hostname": "my-macbook",
  "project": "my-app",
  "sessionId": "01JFF..."
}

The hostname and project fields let you distinguish between machines and projects if you run multiple sessions.

Setup

  1. Install the plugin:

    Add to your ~/.config/opencode/opencode.json:

    {
  "plugin": ["opencode-homeassistant"]
}

  2. Configure your webhook URL:

    Create ~/.config/opencode/opencode-homeassistant.json:

    {
  "webhookUrl": "https://your-ha-instance/api/webhook/your_webhook_id"
}

  3. Create a webhook automation in Home Assistant — no custom integration needed.

Automation ideas

Busy light — change a desk LED color based on agent state (green = busy, yellow = waiting, red = error, off = idle):

automation:
  - alias: OpenCode busy light
    triggers:
      - trigger: webhook
        webhook_id: your_webhook_id
        allowed_methods:
          - POST
        local_only: false
    actions:
      - choose:
          - conditions: "{{ trigger.json.state == 'busy' }}"
            sequence:
              - action: light.turn_on
                target:
                  entity_id: light.desk_led
                data:
                  color_name: green
                  brightness: 128
          - conditions: "{{ trigger.json.state == 'waiting' }}"
            sequence:
              - action: light.turn_on
                target:
                  entity_id: light.desk_led
                data:
                  color_name: yellow
                  brightness: 200
          - conditions: "{{ trigger.json.state == 'error' }}"
            sequence:
              - action: light.turn_on
                target:
                  entity_id: light.desk_led
                data:
                  color_name: red
                  brightness: 255
          - conditions: "{{ trigger.json.state == 'idle' }}"
            sequence:
              - action: light.turn_off
                target:
                  entity_id: light.desk_led

Mobile notification when the agent needs attention:

automation:
  - alias: OpenCode needs attention
    triggers:
      - trigger: webhook
        webhook_id: your_webhook_id
        allowed_methods:
          - POST
        local_only: false
    conditions:
      - condition: template
        value_template: "{{ trigger.json.state in ['waiting', 'error'] }}"
    actions:
      - action: notify.mobile_app_your_phone
        data:
          title: "OpenCode — {{ trigger.json.project }} ({{ trigger.json.hostname }})"
          message: >-
            {% if trigger.json.state == 'waiting' %}Agent is waiting for your input
            {% else %}Agent encountered an error{% endif %}

Links