Unofficial Home Assistant Integration for OpenCode

Note: This is an unofficial community project and is not affiliated with, endorsed by, or supported by OpenCode or Anomaly. OpenCode branding is used in accordance with their brand guidelines.

A native Home Assistant integration for OpenCode, the AI coding assistant. Monitor and control your OpenCode sessions directly from Home Assistant.

Full Documentation | OpenCode Plugin

• Native Integration: Direct WebSocket connection to OpenCode - no MQTT broker required
• Secure Pairing: Simple pairing flow with one-time codes
• Session Monitoring: Track session state, model, tokens, cost, and activity
• Permission Handling: Approve or reject permission requests from Home Assistant
• Send Prompts: Send prompts to OpenCode from automations or the Lovelace card
• Auto-reconnect: Persistent connection with automatic reconnection
• Lovelace Card: Beautiful card for viewing and interacting with sessions
• Blueprints: Ready-to-use automations for mobile notifications

• Home Assistant 2024.1 or later
• OpenCode with the opencode-homeassistant plugin installed

1. Open HACS in Home Assistant
2. Go to "Integrations" section
3. Click the three dots menu > "Custom repositories"
4. Add https://github.com/stephengolub/ha-opencode as "Integration"
5. Search for "OpenCode" and install
6. Restart Home Assistant

1. Download the latest release
2. Extract custom_components/opencode to your Home Assistant config/custom_components/ folder
3. Copy frontend/dist/opencode-card.js to config/www/
4. Restart Home Assistant

1. Go to Settings > Devices & Services
2. Click "Add Integration"
3. Search for "OpenCode"
4. A pairing code will be displayed (e.g., ABC12DEF)

In your OpenCode session, use the ha_pair tool:

Pair with Home Assistant using:
- URL: http://homeassistant.local:8123
- Access Token: <your long-lived access token>
- Code: ABC12DEF

To create a long-lived access token:

1. Go to your Home Assistant profile (click your name in the sidebar)
2. Scroll to "Long-Lived Access Tokens"
3. Click "Create Token"

Add the card resource:

Via UI:

1. Go to Settings > Dashboards
2. Click the three dots menu > Resources
3. Click "Add Resource"
4. URL: /local/opencode-card.js
5. Type: JavaScript Module

Via YAML (in configuration.yaml):

lovelace:
  resources:
    - url: /local/opencode-card.js
      type: module

Copy the blueprints to your Home Assistant config:

mkdir -p config/blueprints/automation/opencode
cp blueprints/automation/*.yaml config/blueprints/automation/opencode/

Then reload automations in Developer Tools > YAML > Reload Automations.

The integration creates these entities for each OpenCode session:

Send a prompt to an OpenCode session.

service: opencode.send_prompt
data:
  session_id: ses_abc123
  text: "Fix the bug in main.py"
  agent: code  # optional

Respond to a permission request.

service: opencode.respond_permission
data:
  session_id: ses_abc123
  permission_id: perm_xyz789
  response: once  # once, always, or reject

Request session history (response sent via event).

service: opencode.get_history
data:
  session_id: ses_abc123

Request available agents (response sent via event).

service: opencode.get_agents
data:
  session_id: ses_abc123

The integration includes ready-to-use blueprints for common automations.

File: blueprints/automation/opencode_state_notifications.yaml

Sends mobile notifications when:

• A task completes (idle after working)
• Permission is required (with approve/reject buttons)
• An error occurs

Features:

• Configurable notification service
• Toggle notifications by type
• Detailed permission info (type, title, pattern)
• Android and iOS support

File: blueprints/automation/opencode_permission_response.yaml

Handles taps on notification action buttons:

• Extracts session and permission IDs
• Calls opencode.respond_permission service
• Works with both iOS and Android

Usage:

1. Install both blueprints
2. Create an automation from "State Notifications" blueprint
3. Create an automation from "Permission Response" blueprint
4. Configure your mobile notification service

Add the card to a dashboard:

type: custom:opencode-card
title: OpenCode Sessions

Basic card:

type: custom:opencode-card

Pinned to specific device:

type: custom:opencode-card
device: opencode_abc123def456

The integration fires these events for automations:

automation:
  - alias: "OpenCode Permission Alert"
    trigger:
      - platform: event
        event_type: opencode_permission_request
    action:
      - service: notify.mobile_app
        data:
          title: "{{ trigger.event.data.title }}"
          message: >
            Type: {{ trigger.event.data.type }}
            Pattern: {{ trigger.event.data.pattern }}

1. Check that OpenCode is running with the plugin installed
2. Verify your access token is valid
3. Check Home Assistant logs for connection errors

1. Verify the WebSocket connection is active (check integration status)
2. Look for errors in Home Assistant logs
3. Try restarting OpenCode and re-pairing

1. Verify the resource is loaded (Developer Tools > Network)
2. Check browser console for JavaScript errors
3. Clear browser cache and reload

1. Ensure both blueprints are installed
2. Check that the notification service is correct
3. Verify mobile app is connected to HA

# Frontend (Lovelace card)
npm install
npm run build

# Development with auto-rebuild
npm run dev

Full documentation is available at stephengolub.github.io/ha-opencode

• Installation
• Setup Guide
• Entities Reference
• Services Reference
• Lovelace Card
• Blueprints
• Automations
• Troubleshooting

• opencode-homeassistant - OpenCode plugin (required) (docs)
• OpenCode - AI coding assistant

MIT