Discord connector for herdctl fleet management
npm install @herdctl/discord> Discord connector for herdctl fleet management
Documentation: herdctl.dev
@herdctl/discord enables your herdctl agents to interact via Discord. Users can chat with agents in DMs or channels, and agents can send notifications when jobs complete. The connector handles session management automatically, maintaining conversation context across messages.
``bash`
npm install @herdctl/discord
> Note: This package is typically used automatically by @herdctl/core when Discord is configured in your agent YAML. Direct installation is only needed for advanced use cases.
Add Discord chat configuration to your agent YAML:
`yaml
name: my-assistant
model: claude-sonnet-4-20250514
chat:
discord:
bot_token_env: MY_ASSISTANT_DISCORD_TOKEN
guilds: [] # Empty array = no channel restrictions
dm:
enabled: true
mode: auto # Respond to all DMs automatically
`
`yaml
name: support-bot
model: claude-sonnet-4-20250514
chat:
discord:
bot_token_env: SUPPORT_BOT_DISCORD_TOKEN
guilds:
- id: "123456789012345678" # Your server ID
channels:
- id: "987654321098765432"
name: "#support" # Optional, for logging
mode: mention # Only respond when @mentioned
- id: "111222333444555666"
name: "#general"
mode: auto # Respond to all messages
dm:
enabled: true
mode: auto
`
`yaml
chat:
discord:
# Required: Environment variable containing bot token
bot_token_env: DISCORD_BOT_TOKEN
# Optional: Session expiry in hours (default: 24)
session_expiry_hours: 24
# Optional: Log verbosity (default: standard)
log_level: standard # minimal | standard | verbose
# Optional: Bot presence/activity
presence:
activity_type: watching # playing | watching | listening | competing
activity_message: "for support requests"
# Required: Guild (server) configurations (can be empty array for DM-only)
guilds:
- id: "123456789012345678"
channels:
- id: "987654321098765432"
name: "#support"
mode: mention # mention | auto
context_messages: 10 # Messages to include for context
# Per-guild DM settings (optional, overrides global)
dm:
enabled: true
mode: auto
# Optional: Global DM configuration
dm:
enabled: true
mode: auto # mention | auto
allowlist: ["user-id-1", "user-id-2"] # Only these users can DM
blocklist: ["blocked-user-id"] # These users cannot DM
`
- auto - Respond to all messages in allowed channels/DMs
- mention - Only respond when the bot is @mentioned
Each agent can have its own Discord bot with a unique token. Simply use different environment variable names:
`yamlAgent 1: Support Bot
name: support-bot
chat:
discord:
bot_token_env: SUPPORT_BOT_TOKEN
# ...
Then set both environment variables:
bash
export SUPPORT_BOT_TOKEN="your-support-bot-token"
export DEV_ASSISTANT_TOKEN="your-dev-assistant-token"
`This allows you to run multiple agents with different Discord identities, each with their own bot user, avatar, and permissions.
Features
- Conversation Continuity - Sessions persist across messages using Claude SDK session resumption
- DM Support - Users can chat privately with agents
- Channel Support - Agents can participate in server channels
- Per-Agent Bots - Each agent can have its own Discord bot identity
- Slash Commands - Built-in
, /reset, and /help commands
- Typing Indicators - Visual feedback while agent is processing
- Message Splitting - Long responses are automatically split to fit Discord's limitsSlash Commands
| Command | Description |
|---------|-------------|
|
/help | Show available commands and usage |
| /status | Show agent status and current session info |
| /reset | Clear conversation context (start fresh) |Bot Setup
1. Create a Discord application at discord.com/developers
2. Add a bot to your application
3. Enable the "Message Content Intent" in bot settings
4. Generate an invite URL with these permissions:
- Send Messages
- Read Message History
- Use Slash Commands
5. Invite the bot to your server
6. Set your bot token as an environment variable (use a unique name per bot)
Documentation
For complete setup instructions, visit herdctl.dev:
- Discord Integration Guide
- Chat Configuration
Related Packages
herdctl - CLI for running agent fleets
- @herdctl/core` - Core library for programmatic useMIT