Skip to content

README.md

Latest commit

 

History

History
170 lines (117 loc) · 5.31 KB

README.md

File metadata and controls

170 lines (117 loc) · 5.31 KB

Discord Maestro Bot

Made with Maestro

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

Features

  • Creates dedicated Discord channels for Maestro agents
  • Per-user session threads — start one with /session new or by @mentioning the bot in an agent channel
  • 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 available on your PATH (no authentication required)

Install maestro-discord CLI

The maestro-discord CLI lets your Maestro agents reach out to you on Discord — for example, to ping you when a long-running task finishes. See docs/api.md for usage.

After building the project (npm run build), create a shell wrapper.

macOS / Linux:

printf '#!/bin/bash\nnode "%s/dist/cli/maestro-discord.js" "$@"\n' "$(pwd)" | sudo tee /usr/local/bin/maestro-discord && sudo chmod +x /usr/local/bin/maestro-discord

Windows (PowerShell) — writes the wrapper to %USERPROFILE%\bin and adds it to your user PATH:

$repoPath = (Get-Location).Path
$binDir = "$env:USERPROFILE\bin"
New-Item -ItemType Directory -Force -Path $binDir | Out-Null
@"
@echo off
node "$repoPath\dist\cli\maestro-discord.js" %*
"@ | Out-File -FilePath "$binDir\maestro-discord.cmd" -Encoding ASCII

# Add $binDir to user PATH if it isn't already (restart your shell afterwards)
$userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
if (-not ($userPath -split ';' -contains $binDir)) {
    [Environment]::SetEnvironmentVariable('PATH', "$binDir;$userPath", 'User')
}

Or use npm link:

npm link

Quick start

  1. Install dependencies:
npm install
  1. 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
API_PORT=3457                     # Optional: port for internal API (default 3457)
DISCORD_MENTION_USER_ID=          # Optional: Discord user ID to @mention when --mention is used
  1. Deploy slash commands:
npm run deploy-commands
  1. Start the bot (dev mode):
npm run dev

Production run

npm run build
npm start

Tests

npm test

Coverage:

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

Slash commands

Command Description
/health Verify Maestro CLI is installed and working
/agents list Show all available agents
/agents new <agent> Create a dedicated channel for an agent (autocomplete)
/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
/session new Create a new owner-bound thread for the current agent channel
/session list List session threads for the current agent channel

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, thread ownership model, and project layout.

Maestro-to-Discord Messaging

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

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

Invite the bot with both bot and applications.commands scopes:

https://discord.com/oauth2/authorize?client_id=<DISCORD_CLIENT_ID>&scope=bot+applications.commands&permissions=11344

This grants the following permissions:

  • Manage Channels
  • Add Reactions
  • View Channels
  • Send Messages
  • Manage Messages

Then enable Message Content Intent under Privileged Gateway Intents at:

https://discord.com/developers/applications/<DISCORD_CLIENT_ID>/bot

Without this the bot will fail to connect with a "Used disallowed intents" error.

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.
  • If commands don’t appear, re-run npm run deploy-commands after updating your bot or application settings.