ha-opencode

OpenCode Home Assistant Plugin

Unofficial Home Assistant Plugin 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.

OpenCode plugin that enables real-time integration with Home Assistant via native WebSocket connection.

Monitor and control your OpenCode sessions directly from Home Assistant - get notified when tasks complete, approve permissions from your phone, and even send prompts remotely.

Full Documentation | Home Assistant Integration

Features

• Native WebSocket: Direct connection to Home Assistant - no MQTT broker required
• Secure Pairing: Simple one-time pairing flow with secure token authentication
• Real-time Updates: Instant session state, model, tool, token, and cost updates
• Permission Handling: Approve/reject tool permissions from Home Assistant or mobile notifications
• Session History: Retrieve full conversation history on demand
• Multi-session Support: Each session gets its own device in Home Assistant
• Auto-reconnect: Persistent connection with automatic reconnection

Requirements

• OpenCode AI coding assistant
• Home Assistant with the companion integration installed:
  • ha-opencode - Home Assistant integration (required)

Installation

1. Install the Plugin

# From npm (when published)
npm install --prefix ~/.config/opencode ha-opencode

# Or from local path
npm install --prefix ~/.config/opencode /path/to/opencode-homeassistant

2. Add to OpenCode Config

Add "ha-opencode" to the plugins array in ~/.config/opencode/opencode.json:

{
  "plugins": ["ha-opencode"]
}

3. Install the Home Assistant Integration

The plugin requires the companion Home Assistant integration. See ha-opencode for installation instructions.

4. Pair with Home Assistant

• In Home Assistant, go to Settings > Devices & Services
• Add the "OpenCode" integration
• A pairing code will be displayed (e.g., ABC12DEF)
• In OpenCode, use the ha_pair tool with:
  • Your Home Assistant URL (e.g., http://homeassistant.local:8123)
  • A long-lived access token
  • The pairing code

Once paired, the plugin will automatically reconnect on subsequent OpenCode sessions.

Configuration

The plugin stores connection configuration in ~/.config/opencode/ha-config.json after pairing:

{
  "url": "ws://homeassistant.local:8123/api/websocket",
  "accessToken": "your-access-token",
  "instanceToken": "generated-during-pairing",
  "instanceId": "instance_abc123"
}

You can also set the Home Assistant URL and access token via environment variables:

export OPENCODE_HA_URL=http://homeassistant.local:8123
export OPENCODE_HA_ACCESS_TOKEN=your-access-token

How It Works

┌─────────────────┐    WebSocket     ┌──────────────────┐
│                 │◄────────────────►│                  │
│    OpenCode     │                  │  Home Assistant  │
│    + Plugin     │                  │  + Integration   │
│                 │                  │                  │
└─────────────────┘                  └──────────────────┘
                                            │
                                            ▼
                                    ┌──────────────────┐
                                    │  Lovelace Card   │
                                    │  Mobile App      │
                                    │  Automations     │
                                    └──────────────────┘

• Plugin connects to Home Assistant via WebSocket
• Session updates are sent in real-time (state, model, tokens, cost, permissions)
• Commands flow back from HA (send prompt, respond to permission, get history)
• Events are fired in HA for automations (state changes, permission requests)

Commands from Home Assistant

The plugin responds to these commands sent via the Home Assistant integration:

Command	Description
send_prompt	Send a text prompt to the current session
respond_permission	Approve (once/always) or reject a permission request
get_history	Retrieve session conversation history
get_agents	Get list of available agents

Session Data

Each OpenCode session reports the following to Home Assistant:

Data	Description
state	Session state: idle, working, waiting_permission, error
title	Session/conversation title
model	AI model being used (e.g., anthropic/claude-sonnet-4-20250514)
current_tool	Currently executing tool
tokens_input	Total input tokens used
tokens_output	Total output tokens used
cost	Total session cost in USD
last_activity	Timestamp of last activity
agent	Primary agent selected
current_agent	Sub-agent currently executing
hostname	Machine hostname
permission	Pending permission details (if any)

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Project Structure

src/
  index.ts        Plugin entry point
  websocket.ts    Home Assistant WebSocket client
  state.ts        Session state tracking
  commands.ts     Command handler (prompts, permissions, history)
  ha-config.ts    Configuration storage
  notify.ts       Terminal notifications (Kitty OSC 99)

tests/
  *.test.ts       Unit tests

Troubleshooting

Plugin not connecting

• Verify the Home Assistant integration is installed and configured
• Check that your access token is valid (test in Developer Tools > API)
• Look for connection errors in OpenCode output
• Try re-pairing: delete ~/.config/opencode/ha-config.json and pair again

Permission responses not working

• Ensure the session is still active (not disconnected)
• Check Home Assistant logs for errors
• Verify the permission ID matches the pending permission

Notifications not appearing

This plugin uses Kitty terminal notifications (OSC 99). Supported terminals:

• Kitty
• iTerm2 (with notifications enabled)

If your terminal doesn't support OSC 99, notifications will be silent.

Documentation

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

• Installation Guide
• Configuration
• Pairing with Home Assistant
• Session Tracking
• Commands
• Permissions

Related Projects

• ha-opencode - Home Assistant integration with Lovelace card and blueprints (docs)
• OpenCode - AI coding assistant

License

MIT