Maestro Relay

Maestro Relay connects chat platforms to Maestro AI agents through maestro-cli. Discord and Slack ship in the box; Teams, Matrix, and others can be added by dropping in a provider adapter — the kernel is provider-agnostic.

Migrating from discord-maestro? Same codebase, new name. All DISCORD_* env vars work unchanged; the legacy maestro-discord binary has been retired in favour of maestro-relay. See "Migration" below.

Features

• Provider-pluggable kernel — Discord and Slack today, Teams/Matrix next
• Creates dedicated channels for Maestro agents
• Per-user session threads (/session new or by mentioning the bot)
• Optional ambient mode — the agent follows a channel conversation and speaks only when it has something to add (docs/ambient.md)
• Per-conversation FIFO queue with typing/reaction indicators
• Streams agent replies back into chat with usage stats
• Voice transcription pipeline (whisper.cpp) for Discord voice messages
• Optional prompt-injection screening (0din.ai SusFactor) with log/flag/block modes (docs/susfactor.md)

Prerequisites

• Node.js 22+
• A bot token for at least one supported provider (Discord or Slack)
• Maestro CLI on your PATH

Install (production one-liner)

bash -c "$(curl -fsSL https://raw.githubusercontent.com/RunMaestro/Maestro-Relay/main/install.sh)"

After install:

maestro-relay-ctl start     # boot the bot
maestro-relay-ctl logs      # tail logs
maestro-relay-ctl status    # service status
maestro-relay-ctl update    # upgrade to latest release (preserves config)
maestro-relay-ctl uninstall # remove install + service files

Quick start

Path	Purpose
~/.local/share/maestro-relay/	Installed bot (built JS + dependencies)
~/.config/maestro-relay/.env	Configuration (preserved across updates)
~/.local/bin/maestro-relay-ctl	Service control wrapper
~/.local/bin/maestro-relay	Agent → chat CLI (send, notify, status)
systemd user / launchd agent	Auto-start unit

Override any of these with MAESTRO_RELAY_HOME, XDG_CONFIG_HOME, or MAESTRO_RELAY_BIN_DIR. Pin a specific version with MAESTRO_RELAY_VERSION=v1.0.0. Choose a provider module at install time via MAESTRO_RELAY_MODULE (discord or slack).

Release channels (stable vs RC)

The installer and maestro-relay-ctl update track the stable channel by default — the latest non-prerelease GitHub release. To try release candidates ahead of a stable cut, opt into the rc channel:

maestro-relay-ctl channel rc      # persist the preference, then:
maestro-relay-ctl update          # pulls the newest release, prereleases included
maestro-relay-ctl update --rc     # …or switch + update in one step
maestro-relay-ctl channel stable  # switch back (or: update --stable)

For a fresh install on the RC channel, set the env var:

MAESTRO_RELAY_CHANNEL=rc bash -c "$(curl -fsSL https://raw.githubusercontent.com/RunMaestro/Maestro-Relay/main/install.sh)"

RC builds are published as GitHub prereleases (tags like v0.5.0-rc.1), so the stable channel never picks them up. Pin an exact build with MAESTRO_RELAY_VERSION=vX.Y.Z-rc.N. The persisted channel lives at ~/.config/maestro-relay/channel.

Install (development from source)

1. Clone and install:

git clone https://github.com/RunMaestro/Maestro-Relay.git
cd Maestro-Relay
npm install

2. Configure environment:

cp .env.example .env

Set core values in .env:

ENABLED_PROVIDERS=discord    # comma-separated; default 'discord'. Use 'slack' or 'discord,slack' for multi-provider deployments
API_PORT=3457                # optional, default 3457

Then fill in the provider-specific keys. The Discord provider needs DISCORD_BOT_TOKEN, DISCORD_CLIENT_ID, and DISCORD_GUILD_ID — see docs/discord.md for bot setup, the full env-var reference, and slash-command deployment. The Slack provider needs SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, SLACK_TEAM_ID, and SLACK_APP_ID — see docs/slack.md. For optional voice transcription (Discord), see docs/voice.md.

3. Deploy slash commands (Discord):

npm run deploy-commands

4. Start the bridge (dev mode):

npm run dev

Optional for source-based local CLI usage:

npm link

Production run

npm run build
npm start

Tests

npm test

Coverage:

npm run build && node --test --experimental-test-coverage dist/__tests__/**/*.test.js

Providers

Provider	Docs	Status
Discord	docs/discord.md — bot setup, env vars, slash commands, runtime behavior	Built-in
Slack	docs/slack.md — app setup, env vars, slash commands, runtime behavior	Built-in
Teams / Matrix / …	AGENTS-providers.md — provider development guide	Add your own

Optional voice transcription (whisper.cpp, Discord-only today): docs/voice.md.

Optional ambient mode (Discord-only today): docs/ambient.md. Optional prompt-injection screening for every provider: docs/susfactor.md.

How it works

Mention the bot or run /session new in an agent channel to create a thread, then chat — messages are queued and forwarded to the agent via maestro-cli. See docs/architecture.md for the full message flow and kernel/provider split, and AGENTS-providers.md for the provider-development guide.

Agent → chat messaging

Agents can push messages to chat via the maestro-relay CLI / HTTP API. See docs/api.md for usage, endpoints, and error codes.

Migration from discord-maestro

This project was renamed from discord-maestro / Maestro-Discord. To smooth upgrades:

• The legacy maestro-discord / maestro-bridge binaries have been retired; install + upgrade now scrub any leftover symlinks. Update any scripts that invoke them to maestro-relay send ….
• All DISCORD_* env vars are unchanged. New optional ENABLED_PROVIDERS defaults to discord.
• The SQLite database upgrades automatically on first start: agent_channels gains a provider column (existing rows default to discord); agent_threads is renamed to discord_agent_threads with rows preserved. No manual migration needed.
• The HTTP /api/send endpoint accepts an optional provider field that defaults to discord; existing callers are unaffected.

Data storage

The bridge stores channel ↔ agent mappings in a local SQLite database at maestro-bot.db. Delete this file to reset all channel bindings.