Discord Maestro Bot

A Discord bot that connects your server to Maestro AI agents through maestro-cli.

Features

• Creates dedicated Discord channels for Maestro agents
• Queues messages per channel for orderly processing
• Streams agent replies back into Discord, including usage stats

Prerequisites

• Node.js 18+
• A Discord application + bot token
• Maestro CLI installed and authenticated

CLI docs: https://docs.runmaestro.ai/

Quick start

1. Install dependencies:

npm install

2. Configure environment:

cp .env.example .env

Set these values in .env:

DISCORD_BOT_TOKEN=   # Bot token from Discord Developer Portal
DISCORD_CLIENT_ID=   # Application ID from Discord Developer Portal
DISCORD_GUILD_ID=    # Your server's ID (right-click server → Copy ID)
DISCORD_ALLOWED_USER_IDS=123,456  # Optional: comma-separated user IDs allowed to run slash commands

3. Deploy slash commands:

npm run deploy-commands

4. Start the bot (dev mode):

npm run dev

Production run

npm run build
npm start

Tests

node --test --import tsx

Coverage:

node --test --experimental-test-coverage --import tsx

Slash commands

Command	Description
/health	Verify Maestro CLI is installed and working
/agents list	Show all available agents
/agents new <agent-id>	Create a dedicated channel for an agent
/agents disconnect	(Run inside an agent channel) Remove and delete the channel
/agents readonly on|off	Toggle read-only mode for the current agent channel

How it works

• /agents list reads running agents from Maestro.
• /agents new creates a text channel under the Maestro Agents category.
• Mention flow: in a registered agent channel, user mentions the bot (either @bot user mention or @BotRole role mention) and the bot creates a dedicated thread bound to that user. The triggering message is forwarded to the agent so the user gets an immediate response.
• Only the bound owner can trigger agent responses inside that thread. Messages from other users are silently ignored.
• /session new also creates an owner-bound thread for the command invoker.
• Messages in registered, owner-authorized threads are queued and forwarded to maestro-cli.
• The bot adds a ⏳ reaction while waiting, shows typing, and splits long replies.
• After each response, it posts a small usage footer with tokens, cost, and context.

Data storage

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

Discord bot permissions

• Read Messages / View Channels
• Send Messages
• Manage Channels
• Add Reactions
• Read Message History

Security

• Slash command access can be limited with DISCORD_ALLOWED_USER_IDS.
• Mention-created and /session new threads are bound to a single owner.
• In bound threads, non-owner messages are ignored without bot replies.

Troubleshooting

• If /health fails, ensure maestro-cli is on your PATH and you are logged in.
• If commands don’t appear, re-run npm run deploy-commands after updating your bot or application settings.