GitHub Copilot Bridge Integration

Use GitHub Copilot as a conversational AI agent inside Home Assistant. Talk to it via voice assistants, automations, or the HA chat UI.

Credits

Built on top of the original work by @tserra30 at tserra30/Github-Copilot-SDK-integration. Many thanks for laying the foundation that made this possible.

How it works

This project has two parts that work together:

1. GitHub Copilot Bridge Addon — installs the Copilot CLI binary in a dedicated container and runs it in server mode on port 7681 (internal Supervisor network only)
2. GitHub Copilot Bridge Integration — a custom HA integration that connects to the addon over the internal network and exposes a conversation agent

The integration never touches your GitHub token — authentication is handled entirely by the add-on.

Requirements

• Home Assistant OS or Supervised (the add-on requires the Supervisor)
• A GitHub account with an active Copilot subscription
• A GitHub Personal Access Token with Copilot permissions

Setup

Install in this order: add-on first, then integration.

1. Install the GitHub Copilot Bridge Addon

1. Go to Settings → Add-ons → Add-on Store
2. Click ⋮ (top-right) → Repositories
3. Add: https://github.com/tehmark/Github-Copilot-SDK-integration
4. Find GitHub Copilot Bridge Addon and click Install
5. Open the add-on Configuration tab and fill in your token and port:

   github_token: "ghp_yourTokenHere"
   port: 7681

6. Click Start, then open the Log tab and confirm you see:

   GitHub Copilot Bridge Add-on Starting
   Copilot CLI version: ...
   Starting Copilot CLI in server mode on port 7681 (attempt 1/5)...
   

Getting a token: Go to GitHub Settings → Tokens, create a Personal Access Token, and make sure your account has an active Copilot subscription.

2. Install the GitHub Copilot Bridge Integration

Via HACS (recommended)

1. Open HACS → Integrations → click +
2. Search for GitHub Copilot Bridge Integration and install it
3. Restart Home Assistant

Manual

1. Copy the custom_components/github_copilot directory into your HA custom_components folder
2. Restart Home Assistant

3. Configure the Integration

1. Go to Settings → Devices & Services → Add Integration
2. Search for GitHub Copilot Bridge Integration
3. The Add-on URL field is pre-filled with http://github-copilot-bridge:7681 — this is the fixed hostname set in the add-on
4. Select a Model — after the connection is tested, the dropdown updates to show only models available on your account. Default: claude-haiku-4.5 (fastest Anthropic model, best tool use for HA control, no premium cost)
5. Click Submit — the integration will test the connection to the running add-on

If the URL doesn't work, check the add-on Info tab for the actual hostname. It will look something like 56b5df53-github-copilot-bridge (a hex prefix + your slug). Use http://<hostname>:7681.

Usage

Conversation agent

Once set up, select GitHub Copilot Bridge Integration as the conversation agent in:

• A voice assistant pipeline (Settings → Voice Assistants)
• The HA chat UI

This integration is designed as a heavy-task agent — best for complex, multi-step Home Assistant tasks like building automations, diagnosing issues, or analysing sensor history. Results can be saved to HA helper entities (input_text, note) for a lighter model to read later.

Home Assistant control with ha-mcp (optional)

Install the ha-mcp addon to give Copilot 96 tools to read and control your Home Assistant — devices, automations, scripts, dashboards, and more.

1. Add the ha-mcp repository: Settings → Add-ons → Add-on Store → ⋮ → Repositories → add https://github.com/homeassistant-ai/ha-mcp

2. Install Home Assistant MCP Server and click Start

3. Open the ha-mcp Log tab — you'll see your unique URL:

   🔐 MCP Server URL: http://192.168.1.x:9583/private_AbCdEfGh1234...
   

   This URL is generated once and never changes — copy it now, you only need to do this once.

4. Go to Settings → Devices & Services → GitHub Copilot Bridge Integration → Configure

5. Paste that URL into the MCP Server URL field and click Submit

6. In the ha-mcp addon configuration, enable "Enable tool search" and restart ha-mcp

   Why enable tool search? claude-haiku-4.5 (the default model) lacks "deferred tool loading" — without tool search, all 96 tools (~46K tokens) are sent with every message. With tool search ON, this drops to ~5K tokens and two fast round-trips, which is quicker than one slow 46K-token call.

   Using Sonnet/Opus instead? Those models support deferred tool loading (tools load on-demand at ~0 idle cost), so you can disable tool search for a single round-trip per command. Note: Copilot Pro includes ~300 premium requests/month.

Now Copilot can carry out complex tasks like "Create an automation that runs at sunset and dims the living room lights to 30%" or "Check my sensor history for the past week and save a summary to a note helper".

Note: ha-mcp connects to Home Assistant automatically when installed as an addon — no separate token is needed.

Custom Instructions

Custom Instructions define the agent's role and behaviour. Set them in Settings → Devices & Services → GitHub Copilot Bridge Integration → Configure.

When ha-mcp is configured and the field is empty, a default set of instructions is pre-filled that:

• Identifies the agent as a capable HA task agent
• Directs it to use ha-mcp's tool search pattern
• Instructs it to save task results to a HA helper entity after completion

You can customise or replace these entirely. Useful additions:

• Specific helper entity names to use for saving results (e.g. "Save summaries to input_text.copilot_notes")
• Domain knowledge about your home (e.g. "My 'media room' is in the basement, entity prefix: media_room"_)
• Task constraints (e.g. "Never delete automations without listing them first and confirming")

Automation example

automation:
  - alias: "Ask Copilot for a morning summary"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: conversation.process
        data:
          text: "Good morning! Give me a quick summary of what I should know today."
          agent_id: conversation.github_copilot

Changing the model

Go to Settings → Devices & Services → GitHub Copilot Bridge Integration → Configure to switch models.

The model dropdown is populated live from the Copilot CLI when you open Configure, so you'll always see exactly what's available on your account. The table below shows the current GitHub Copilot model lineup as a reference — GitHub updates this frequently.

Model	Cost	Speed	Notes
claude-haiku-4.5	Included	⚡⚡⚡	Default. Best for voice & HA control — enable tool search in ha-mcp
gpt-5.4-mini	Included	⚡⚡⚡	Fast GPT mini — enable tool search in ha-mcp
gpt-5-mini	Included	⚡⚡⚡	Fast, included — enable tool search in ha-mcp
gpt-5.1-codex-mini	Included	⚡⚡⚡	Fast, code-optimised, included
gpt-4.1	Included	⚡⚡⚡	Fast, included
gpt-5.1	Premium	⚡⚡	Balanced quality — disable tool search (deferred tools)
gpt-5.2	Premium	⚡⚡	Balanced quality — disable tool search (deferred tools)
gpt-5.1-codex	Premium	⚡⚡	Code-focused
gpt-5.2-codex	Premium	⚡⚡	Code-focused
gpt-5.3-codex	Premium	⚡⚡	Code-focused
claude-sonnet-4	Premium	⚡⚡	Anthropic Sonnet — disable tool search (deferred tools)
claude-sonnet-4.5	Premium	⚡⚡	Anthropic Sonnet — disable tool search (deferred tools)
claude-sonnet-4.6	Premium	⚡⚡	Latest Anthropic Sonnet — disable tool search (deferred tools)
gemini-3-pro-preview	Premium	⚡⚡	Google Gemini
gpt-5.4	Premium (high)	⚡	Most capable GPT
gpt-5.1-codex-max	Premium (high)	⚡	Max code model
claude-opus-4.5	Premium (high)	⚡	Anthropic flagship — disable tool search (deferred tools)
claude-opus-4.6	Premium (high)	⚡	Latest Anthropic Opus — disable tool search (deferred tools)

Tip for voice / HA control: Use claude-haiku-4.5 (default) with "Enable tool search" ON in ha-mcp. Haiku lacks deferred tool loading, so tool search keeps context small (~5K vs 46K tokens) and response times fast. For premium models (Sonnet/Opus), disable tool search — they support deferred loading. Check github.com/features/copilot/plans for current model availability.

Troubleshooting

Check the add-on Log tab first — it logs the CLI version, each startup attempt, and every line of output from the Copilot process (prefixed with [copilot]). Then check Settings → System → Logs for integration-level errors.

Symptom	Check
Add-on fails to start (exit code non-zero)	Add-on logs — look for the [copilot] lines showing the exact error
"Connection refused" in HA logs	Is the add-on running? Is the URL/port correct?
"Protocol version mismatch" in HA logs	Update the integration — the SDK version must match the CLI. Delete and re-add the integration after updating.
"Add-on URL" field — wrong hostname	The add-on uses the fixed hostname github-copilot-bridge. Use http://github-copilot-bridge:7681
"Authentication failed"	Is the github_token in add-on config valid? Does the account have a Copilot subscription?
Integration setup fails with "connection" error	Start the GitHub Copilot Bridge Addon before setting up the integration
Empty or no response	Check GitHub service status; try again

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

This project is licensed under the GNU GPLv3 — see LICENSE for details. Some source code was originally licensed under the MIT License.

This integration depends on the GitHub Copilot SDK, licensed under the MIT License.

This project is not officially affiliated with GitHub or Microsoft.

---