AI and Voice Control

Beacon supports four approaches for voice and AI control. Choose the one that fits your setup, or use them all together.

Claude Code Plugin

The Beacon plugin for Claude Code gives you slash commands, domain knowledge (skills), and the MCP server in one package. Install it once and Claude understands how to manage your family dashboard.

Installation

/plugin marketplace add asachs01/beacon

Then restart Claude Code. That’s it — the plugin, skills, commands, and MCP server are all installed.

Then set your environment variables:

export BEACON_HA_TOKEN="your-ha-long-lived-access-token"
export BEACON_HA_URL="http://homeassistant.local:8123"
export BEACON_DATA_DIR="/path/to/beacon/data"

Generate a token in Home Assistant: Profile > Security > Long-Lived Access Tokens > Create Token.

Slash Commands

Skills

Skills are domain knowledge files that teach Claude how Beacon works. They activate automatically when you ask about related topics.

Example Usage

> /create-chore "Walk the dog" --assigned_to "Lennon, Elliott" --frequency daily --value 1.00 --icon 🐕

> /family-schedule
📅 Family Schedule — Wednesday, April 2
👨 Aaron: 9:00 AM - Team standup, 2:00 PM - Dentist
👩 Ashley: 10:00 AM - PTA meeting
🧒 Lennon: (nothing today)
🧒 Elliott: (nothing today)

> /whats-for-dinner
🌙 Dinner: Instant Pot Spaghetti

> /chore-status
✅ Make bed — Lennon, Elliott
⬜ Walk the dog — pending (Lennon, Elliott)
💰 Lennon: $1.50 today

Voice API (built-in)

Beacon’s server exposes a REST endpoint for natural-language commands. It uses keyword matching — no LLM, no cloud service, and no added latency.

Endpoint

POST /beacon-action/voice
Content-Type: application/json

{ "text": "add milk to the grocery list" }

Response

{
  "response": "Added milk to grocery",
  "action": "add_item",
  "entity_id": "todo.grocery",
  "success": true
}

Supported commands

Lists: add <item> to <list> | mark <item> as done | check off <item> | complete <item>

Media: play | pause | next song | skip | set volume to 50

Navigation: show <view> | open <view> | go to <view>

Queries: what's on today | today's schedule | what's the weather

Examples

# Add a grocery item
curl -X POST http://<beacon-host>:8099/beacon-action/voice \
  -H 'Content-Type: application/json' \
  -d '{"text": "add eggs to the grocery list"}'

# Control media
curl -X POST http://<beacon-host>:8099/beacon-action/voice \
  -H 'Content-Type: application/json' \
  -d '{"text": "set volume to 40"}'

# Check the calendar
curl -X POST http://<beacon-host>:8099/beacon-action/voice \
  -H 'Content-Type: application/json' \
  -d '{"text": "what'\''s on my calendar"}'

The API resolves list names and media players by fuzzy-matching against available HA entities. For media commands, it automatically picks the active player (playing > paused > first available).

MCP Server (for LLM agents)

The Model Context Protocol (MCP) server exposes Beacon’s features as structured tools that LLM agents can call. This is the best approach for AI-powered automation where an LLM decides which actions to take.

The server supports two transports:

• stdio (default) — for Claude Code, Claude Desktop, and other MCP clients that spawn a subprocess
• Streamable HTTP — for web-based clients like Open Claw, Copilot Studio, and any remote MCP consumer

Option 1: stdio transport (Claude Code, Claude Desktop)

For Claude Code:

claude mcp add beacon -- node /path/to/beacon/mcp-server.cjs

For Claude Desktop or other local MCP clients, add to your config file:

{
  "mcpServers": {
    "beacon": {
      "command": "node",
      "args": ["beacon/mcp-server.cjs"],
      "env": {
        "SUPERVISOR_TOKEN": "your-long-lived-access-token",
        "HA_URL": "http://your-ha-instance:8123"
      }
    }
  }
}

Option 2: Streamable HTTP transport (Open Claw, Copilot Studio, remote clients)

Start the server in HTTP mode:

MCP_TRANSPORT=http \
MCP_PORT=3001 \
MCP_API_KEY=your-secret-key \
SUPERVISOR_TOKEN=your-ha-token \
HA_URL=http://your-ha-instance:8123 \
  node beacon/mcp-server.cjs

Or use the --http flag:

node beacon/mcp-server.cjs --http

The server exposes:

Authentication: When MCP_API_KEY is set, all requests must include either:

• Authorization: Bearer <key> header, or
• X-API-Key: <key> header

For Open Claw / other HTTP MCP clients, point them at:

http://your-beacon-host:3001/mcp

For the Beacon HA add-on, the MCP HTTP server can be exposed alongside the web UI. Set MCP_TRANSPORT=http in the add-on configuration to enable it on port 3001.

Environment variables

All 19 tools

Lists

List names are fuzzy-matched. Pass "grocery", "shopping list", or "todo.shopping_list".

Calendar

For all-day events, pass date strings ("2026-04-07") and set all_day: true.

Media

For volume, also pass volume_level (0.0 to 1.0).

Weather

Chores

Family & Payouts

Meal Plans

Example conversation

You: Create a daily chore called “Make bed” for Lennon and Elliott, worth 50 cents each.

The LLM calls beacon_list_family_members to confirm names, then beacon_create_chore with name “Make bed”, assigned_to [“Lennon”, “Elliott”], frequency “daily”, value_cents 50.

HA Custom Sentences (for HA Assist)

Beacon ships with custom sentence and intent handler files for Home Assistant Assist. Once installed, you can use voice commands through any Assist-enabled device — smart speakers, the HA companion app, or the Assist dialog in HA.

Available voice commands

Installation

Run the included install script:

# Auto-detect the HA config directory
beacon/scripts/install-voice-intents.sh

# Or specify it
beacon/scripts/install-voice-intents.sh /config

Then reload the Conversation integration: Developer Tools > YAML > Conversation.

Prerequisites

The intents reference these entities by default. Create or rename them to match:

If your entities have different names, edit the installed YAML files in your HA config directory (custom_intents/beacon.yaml and custom_sentences/en/beacon.yaml).

Customizing

The sentence files use HA’s custom sentence syntax:

• [the] means the word is optional
• {item} captures a text slot
• Multiple patterns per intent are supported

To add new phrasings, edit /config/custom_sentences/en/beacon.yaml. To add another language, create a file like /config/custom_sentences/es/beacon.yaml with the same intent names and translated sentences.