Agent DiscordBot

A TypeScript CLI tool that enables AI agents and humans to interact with Discord servers using bot tokens. Unlike agent-discord which extracts user tokens from the desktop app, agent-discordbot uses standard Discord Bot tokens for server-side and CI/CD integrations.

Quick Start

CODEBLOCK0

Authentication

Bot Token Setup

agent-discordbot uses Discord Bot tokens which you create in the Discord Developer Portal:

CODEBLOCK1

Getting a Bot Token

1. 1. Go to discord.com/developers/applications
2. Click New Application, give it a name, and create
3. Go to Bot in the left sidebar
4. Click Reset Token (or Copy if the token is still visible)
5. Copy the token and store it securely

Inviting the Bot to a Server

After creating the application:

1. 1. Go to OAuth2 > URL Generator in the left sidebar
2. Under Scopes, select INLINECODE0
3. Under Bot Permissions, select the permissions your bot needs (Send Messages, Read Message History, etc.)
4. Copy the generated URL and open it in your browser
5. Select the server and authorize

Message Content Privileged Intent

Bots in 100 or more servers require verification (you can apply once you reach 75+ servers), and verified bots must apply for access to the Message Content intent. Enable it to read message content:

1. 1. Go to discord.com/developers/applications
2. Select your application
3. Go to Bot in the left sidebar
4. Under Privileged Gateway Intents, enable Message Content Intent
5. Save changes

Without this, verified bots receive empty content fields (DMs and mentions are exempt).

Multi-Bot Management

Store multiple bot tokens and switch between them:

CODEBLOCK2

The --bot <id> flag is available on all commands to override the active bot for a single invocation.

Memory

The agent maintains a ~/.config/agent-messenger/MEMORY.md file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the Read and Write tools to manage your memory file.

Reading Memory

At the start of every task, read ~/.config/agent-messenger/MEMORY.md using the Read tool to load any previously discovered server IDs, channel IDs, user IDs, and preferences.

• - If the file doesn't exist yet, that's fine — proceed without it and create it when you first have useful information to store.
• If the file can't be read (permissions, missing directory), proceed without memory — don't error out.

Writing Memory

After discovering useful information, update ~/.config/agent-messenger/MEMORY.md using the Write tool. Write triggers include:

• - After discovering server IDs and names (from server list, etc.)
• After discovering useful channel IDs and names (from channel list, etc.)
• After discovering user IDs and names (from user list, etc.)
• After the user gives you an alias or preference ("call this the alerts bot", "my main server is X")
• After setting up bot identifiers (from auth list)

When writing, include the complete file content — the Write tool overwrites the entire file.

What to Store

• - Server IDs with names
• Channel IDs with names and categories
• User IDs with display names
• Bot identifiers and their purposes
• User-given aliases ("alerts bot", "announcements channel")
• Any user preference expressed during interaction

What NOT to Store

Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and channel context). Never store file upload contents.

Handling Stale Data

If a memorized ID returns an error (channel not found, server not found), remove it from MEMORY.md. Don't blindly trust memorized data — verify when something seems off. Prefer re-listing over using a memorized ID that might be stale.

Format / Example

CODEBLOCK3

Memory lets you skip repeated channel list and server list calls. When you already know an ID from a previous session, use it directly.

Commands

Auth Commands

CODEBLOCK4

Server Commands

CODEBLOCK5

Message Commands

CODEBLOCK6

Channel Commands

CODEBLOCK7

User Commands

CODEBLOCK8

Reaction Commands

CODEBLOCK9

File Commands

CODEBLOCK10

Thread Commands

CODEBLOCK11

Snapshot Command

Get comprehensive server state for AI agents:

CODEBLOCK12

Returns JSON with:

• - Server metadata (id, name)
• Channels (id, name, type, topic)
• Recent messages (id, content, author, timestamp)
• Members (id, username, global_name)

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

CODEBLOCK13

Pretty (Human-Readable)

Use --pretty flag for formatted output:

CODEBLOCK14

Global Options

Common Patterns

See references/common-patterns.md for typical AI agent workflows.

Templates

See templates/ directory for runnable examples:

• - post-message.sh - Send messages with error handling
• INLINECODE25 - Monitor channel for new messages
• INLINECODE26 - Generate server summary

Error Handling

All commands return consistent error format:

CODEBLOCK15

Common errors:

• - missing_token: No credentials configured
• INLINECODE28: Token is invalid or expired
• INLINECODE29: Bot lacks permission for this action
• INLINECODE30: Invalid channel ID
• INLINECODE31: Bot role doesn't have the required permission

Configuration

Credentials stored in: INLINECODE32

Format:
CODEBLOCK16

Security: File permissions set to 0600 (owner read/write only)

Key Differences from agent-discord

Limitations

• - No real-time events / Gateway connection
• No voice channel support
• No server management (create/delete channels, roles)
• No slash commands
• No webhook support
• No message search
• No DMs or friend management
• Bot can only edit/delete its own messages
• Bot must be invited to the server and have appropriate permissions
• Message Content intent required for verified bots (100+ servers)
• Plain text messages only (no embeds in v1)

Troubleshooting

agent-discordbot: command not found

agent-discordbot is NOT the npm package name. The npm package is agent-messenger.

If the package is installed globally, use agent-discordbot directly:

CODEBLOCK17

If the package is NOT installed, use bunx agent-messenger discordbot:

CODEBLOCK18

NEVER run bunx agent-discordbot -- it will fail or install a wrong package since agent-discordbot is not the npm package name.

Bot can't read messages in large servers

Enable the Message Content Intent in the Developer Portal:

1. 1. Go to discord.com/developers/applications
2. Select your application > Bot
3. Enable Message Content Intent under Privileged Gateway Intents
4. Save changes

This is required for verified bots (those in 100 or more servers).

"Missing Access" or "Missing Permissions"

The bot's role doesn't have the required permissions in that channel:

1. 1. Check the bot's role permissions in Server Settings > Roles
2. Check channel-specific permission overrides
3. Make sure the bot can see and send messages in the target channel

"Unknown Channel"

The channel ID is invalid, or the bot doesn't have access to it. Use channel list to find valid channel IDs.

Token expired or invalid

Bot tokens don't expire on their own, but they can be reset:

1. 1. Go to discord.com/developers/applications
2. Select your application > Bot > Reset Token
3. Copy the new token
4. Run INLINECODE41

References

• - Authentication Guide
• Common Patterns