Chat Transports

Huskies can be controlled via bot commands in any of five transports. Only one external transport can be active at a time. The web UI is always available regardless.

Configuration: Copy the relevant example file to .huskies/bot.toml and fill in your credentials. The file is gitignored. Restart huskies after changes.

Web UI

The built-in web interface is always available at http://localhost:<port>. No configuration required. It provides:

Pipeline board showing all work items and their stages
Agent status panel with live output streaming
Chat interface for running commands and talking to Claude
Coverage and cost dashboards

No bot.toml is required for the web UI. If no transport is configured, huskies runs in web-only mode.

Matrix

Matrix uses the Matrix Client-Server API with long-polling sync. No public webhook URL is required — the bot connects outbound to your homeserver.

Setup

Register a Matrix account for the bot on your homeserver (e.g. @huskies:example.com).
Invite the bot account to the rooms you want it to monitor.

Copy the example config and fill in your credentials:

cp .huskies/bot.toml.matrix.example .huskies/bot.toml

bot.toml fields

Key	Description
homeserver	Your Matrix homeserver URL (e.g. `https://matrix.example.com`).
username	Bot account Matrix ID (e.g. `@huskies:example.com`).
password	Bot account password.
room_ids	List of room IDs to listen in (e.g. `["!roomid:example.com"]`).
allowed_users	Matrix IDs allowed to interact. Empty list means nobody — always set this.
ambient_rooms	Rooms where the bot responds to all messages (not just addressed ones). Updated automatically by `ambient on/off`.

Slack

Slack uses event subscriptions over a webhook. You'll need a public HTTPS URL pointing to your huskies server.

Setup

Create a Slack App at api.slack.com/apps.
Add OAuth scopes: chat:write, chat:update.
Subscribe to bot events: message.channels, message.groups, message.im.
Install the app to your workspace and copy the bot token.
Set your webhook URL in Event Subscriptions: https://your-server/webhook/slack

Copy the example config:

cp .huskies/bot.toml.slack.example .huskies/bot.toml

bot.toml fields

Key	Description
slack_bot_token	OAuth bot token starting with `xoxb-`.
slack_signing_secret	Signing secret from the app's Basic Information page.
slack_channel_ids	List of channel IDs to listen in (e.g. `["C01ABCDEF"]`).

WhatsApp (Meta Cloud API)

Connects huskies to WhatsApp Business via the Meta Cloud API. Requires a Meta Business account and a public webhook URL.

Setup

Create a Meta Business App at developers.facebook.com.
Add the WhatsApp product and get a Phone Number ID.
Generate a permanent access token.
Register your webhook URL in Meta's dashboard: https://your-server/webhook/whatsapp

Copy the example config:

cp .huskies/bot.toml.whatsapp-meta.example .huskies/bot.toml

bot.toml fields

Key	Description
whatsapp_provider	Set to `"meta"` for the Meta Cloud API.
whatsapp_phone_number_id	Phone Number ID from the Meta dashboard.
whatsapp_access_token	Permanent access token.
whatsapp_verify_token	Webhook verify token — must match what you set in Meta's dashboard.
whatsapp_allowed_phones	Optional. List of phone numbers allowed to interact (e.g. `["+15551234567"]`). When absent, all numbers are allowed.
whatsapp_notification_template	Optional. Name of the approved Meta message template for out-of-window notifications (default: `"pipeline_notification"`).

WhatsApp (Twilio)

An alternative WhatsApp integration using Twilio's WhatsApp API. Requires a Twilio account.

cp .huskies/bot.toml.whatsapp-twilio.example .huskies/bot.toml

Set whatsapp_provider = "twilio" and fill in your Twilio account SID, auth token, and phone numbers. The webhook URL is the same: https://your-server/webhook/whatsapp.

Discord

Connects huskies to Discord using the Discord Gateway WebSocket. No public webhook URL required — the bot connects outbound.

Setup

Create a Discord Application at discord.com/developers/applications.
Go to Bot, create a bot, and copy the token.
Enable Message Content Intent under Privileged Gateway Intents.
Go to OAuth2 → URL Generator, select the bot scope with permissions: Send Messages, Read Message History, Manage Messages.
Use the generated URL to invite the bot to your server.
Right-click target channels → Copy Channel ID (requires Developer Mode enabled in Discord settings).

Copy the example config:

cp .huskies/bot.toml.discord.example .huskies/bot.toml

bot.toml fields

Key	Description
discord_bot_token	Bot token from the Discord developer portal.
discord_channel_ids	List of channel IDs to listen in (e.g. `["123456789012345678"]`).
discord_allowed_users	Optional. Discord user IDs allowed to interact. When absent, all users in configured channels can interact.

Gateway: aggregated notifications

When using huskies --gateway, you can configure the gateway bot to receive notifications from all registered projects in a single room. Events are prefixed with [project-name].

No additional transport is required — the gateway aggregated stream works with any of the transports above. Configure the gateway's .huskies/bot.toml with your transport credentials and set aggregated_notifications_enabled = true (the default). See Configuration → Gateway aggregated stream for the full reference.

No per-project changes needed: Adding a new project to projects.toml does not require editing per-project bot configs — the gateway picks it up automatically.