agent-discordbot

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.

Key Concepts

Before diving in, a few things about Discord Bot integration:

• Bot tokens — Issued from the Discord Developer Portal (discord.com/developers/applications). Bots act as the bot application's user, with their own ID and presence.
• Server (Guild) preference — A bot can be in many servers. Use server switch <id> to set the active server, or pass --server <id> per command.
• Privileged intents — MessageContent, GuildMembers, and GuildPresences are privileged and must be enabled in the Developer Portal before they can be used by the SDK listener.
• Permission gates — Bot capabilities depend on the role's permission flags in each server. Missing permissions return 403 errors.
• Real-time events — Available via the SDK's Gateway listener, not via the CLI.
• Channel resolution — Every <channel> argument accepts a channel ID (snowflake) or an exact channel name (general or #general). IDs skip the lookup and are faster; names fail with Channel not found when nothing matches exactly.
• Thread targeting — --thread <id|name> on message send and file upload posts into a thread. A numeric value is used as the thread ID; a name is matched against the active threads of that channel (thread_not_found / thread_ambiguous otherwise). Archived threads must be targeted by ID (find it with thread list <channel> --archived); posting to an archived thread unarchives it unless it's locked.
• thread_id vs channel_id in output — For a message posted inside a thread, channel_id IS the thread ID. thread_id is only set when a thread was started from that message; otherwise it's null.

Quick Start

# Set your bot token
agent-discordbot auth set your-bot-token

# Verify authentication
agent-discordbot auth status

# Send a message
agent-discordbot message send 1234567890123456789 "Hello from bot!"

# List channels
agent-discordbot channel list

Authentication

Bot Token Setup

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

# Set bot token (validates against Discord API before saving)
agent-discordbot auth set your-bot-token

# Set with a custom bot identifier
agent-discordbot auth set your-bot-token --bot deploy

# Check auth status
agent-discordbot auth status

# Clear stored credentials
agent-discordbot auth clear

For bot token setup, server invite flow, Message Content Intent, and multi-bot management, see references/authentication.md.

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

# Agent Messenger Memory

## Discord Servers (Bot)

- `1234567890123456` — Acme Dev

## Bots (Acme Dev)

- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot

## Channels (Acme Dev)

- `1111111111111111` — #general (General category)
- `2222222222222222` — #engineering (Engineering category)
- `3333333333333333` — #deploys (Engineering category)

## Users (Acme Dev)

- `4444444444444444` — Alice (server owner)
- `5555555555555555` — Bob

## Aliases

- "deploys" → `3333333333333333` (#deploys in Acme Dev)

## Notes

- Deploy Bot is used for CI/CD notifications
- Alert Bot is used for error monitoring

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

# Set bot token
agent-discordbot auth set <token>
agent-discordbot auth set <token> --bot deploy

# Check auth status
agent-discordbot auth status

# Clear all credentials
agent-discordbot auth clear

# List stored bots
agent-discordbot auth list

# Switch active bot
agent-discordbot auth use <bot-id>

# Remove a stored bot
agent-discordbot auth remove <bot-id>

Whoami Command

# Show current authenticated bot
agent-discordbot whoami
agent-discordbot whoami --pretty
agent-discordbot whoami --bot <bot-id>

Server Commands

# List servers the bot is in
agent-discordbot server list

# Show current server
agent-discordbot server current

# Switch active server
agent-discordbot server switch <server-id>

# Get server info
agent-discordbot server info <server-id>

Message Commands

# Send a message
agent-discordbot message send <channel-id> <content>
agent-discordbot message send 1234567890123456789 "Hello world"

# Reply to a message
agent-discordbot message send <channel-id> <content> --reply <message-id>
agent-discordbot message send 1234567890123456789 "On it!" --reply 9876543210987654321

# Send a message into a thread (by ID or by active-thread name); the returned channel_id equals the thread ID
agent-discordbot message send <channel-id> <content> --thread <thread-id|thread-name>
agent-discordbot message send 1234567890123456789 "Hello world" --thread 9876543210987654321
agent-discordbot message send 1234567890123456789 "Hello world" --thread "Deployment Progress"

# Sending directly to a thread ID also works (a thread is a channel)
agent-discordbot message send 9876543210987654321 "Hello thread"

# List messages
agent-discordbot message list <channel-id>
agent-discordbot message list 1234567890123456789 --limit 50

# Get a single message by ID
agent-discordbot message get <channel-id> <message-id>

# Get thread replies
agent-discordbot message replies <channel-id> <message-id>
agent-discordbot message replies 1234567890123456789 9876543210987654321 --limit 50

# Edit a message (bot's own messages only)
agent-discordbot message edit <channel-id> <message-id> <new-content>

# Delete a message (bot's own messages only)
agent-discordbot message delete <channel-id> <message-id> --force

Channel Commands

# List channels in current server
agent-discordbot channel list

# Get channel info
agent-discordbot channel info <channel-id>
agent-discordbot channel info 1234567890123456789

User Commands

# List server members
agent-discordbot user list

# Get user info
agent-discordbot user info <user-id>

Reaction Commands

# Add reaction (use emoji name without colons)
agent-discordbot reaction add <channel-id> <message-id> <emoji>
agent-discordbot reaction add 1234567890123456789 9876543210987654321 thumbsup

# Remove reaction
agent-discordbot reaction remove <channel-id> <message-id> <emoji>

# List reactions on a message: [{ emoji: {id, name}, count, me }]
agent-discordbot reaction list <channel-id> <message-id>

File Commands

# Upload one or more files (max 10) to a channel, optionally with text
agent-discordbot file upload <channel-id> <path...> [--text <text>] [--thread <id|name>] [--reply <message-id>] [--filename <name>]
agent-discordbot file upload 1234567890123456789 ./report.pdf
agent-discordbot file upload 1234567890123456789 ./report.pdf ./chart.png --text "Weekly numbers"

# Upload into a thread, or as a reply
agent-discordbot file upload 1234567890123456789 ./log.txt --thread 9876543210987654321
agent-discordbot file upload 1234567890123456789 ./log.txt --text "Full log attached" --reply 9876543210987654321

# Override the stored filename (single file only)
agent-discordbot file upload 1234567890123456789 ./tmp-8x1.txt --filename build.log

# List files in channel (attachments of the latest 100 messages, one request)
agent-discordbot file list <channel-id>

# Get info for one attachment (id, filename, size, url, content_type)
# Searches back through the latest 1,000 messages and stops at the first match
agent-discordbot file info <channel-id> <file-id>

file upload returns { success, file, files, message_id, channel_id }. file is the first attachment, files has all of them, and channel_id is the thread ID when --thread was used. Every message read path (message send|list|get|replies) includes attachments: [{ id, filename, size, url, content_type }], [] when there are none. There is no fixed size limit in the CLI; Discord decides per server and reports 40005 (or http_413) when a file is too big.

Thread Commands

# Create a thread from a message
agent-discordbot thread create <channel-id> <name>
agent-discordbot thread create 1234567890123456789 "Discussion" --auto-archive-duration 1440

# List active threads (whole server, or one channel's threads)
agent-discordbot thread list
agent-discordbot thread list <channel-id>

# List archived threads of a channel (100 most recently archived; has_more tells you if there are older ones)
agent-discordbot thread list <channel-id> --archived

# Archive a thread
agent-discordbot thread archive <thread-id>

thread list returns { threads: [{ id, name, type, parent_id, archived }], has_more }. --archived needs a channel argument (parent_required otherwise).

Snapshot Command

Get server overview for AI agents (brief by default):

# Brief snapshot (default) — fast, minimal API calls
agent-discordbot snapshot

# Full snapshot — includes messages and members (slow, large output)
agent-discordbot snapshot --full

# Filtered full snapshots
agent-discordbot snapshot --full --channels-only
agent-discordbot snapshot --full --users-only

# Limit messages per channel (only with --full)
agent-discordbot snapshot --full --limit 10

Default returns brief JSON with:

• Server ID
• Channels (id, name) — text channels only
• Hint for next commands

With --full, returns comprehensive 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:

{
  "id": "1234567890123456789",
  "content": "Hello world",
  "author": "bot-username",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Pretty (Human-Readable)

Use --pretty flag for formatted output:

agent-discordbot channel list --pretty

Global Options

Option	Description
--pretty	Human-readable output instead of JSON
--bot <id>	Use a specific bot for this command
--server <id>	Use a specific server for this command

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
• monitor-channel.sh - Monitor channel for new messages
• server-summary.sh - Generate server summary

Error Handling

All commands return consistent error format:

{
  "error": "No credentials. Run \"auth set\" first."
}

Common errors: missing_token, invalid_token, Missing Access, Unknown Channel, Missing Permissions.

Errors specific to sending files and targeting threads:

• empty_message: file upload needs at least one file, or --text alongside it.
• too_many_files: more than 10 files in one upload.
• invalid_filename: --filename is empty, ., .., or contains a path separator.
• thread_not_found: --thread <name> matched no active thread in that channel. Run thread list <channel> (add --archived for archived ones) or pass the thread ID.
• thread_ambiguous: several active threads share that name; the message lists their IDs. Use the ID.
• parent_required: thread list --archived was called without a channel.
• 40005 / http_413: Discord rejected the upload as too large for that server's limit. The error message says so; the CLI doesn't preflight sizes.

Configuration

Credentials stored in ~/.config/agent-messenger/discordbot-credentials.json (0600 permissions). See references/authentication.md for format and security details.

Key Differences from agent-discord

Feature	agent-discord	agent-discordbot
Token type	User token	Bot token
Token source	Auto-extracted from desktop app	Manual from Developer Portal
Message search	Yes	No
DMs	Yes	No
Mentions	Yes	No
Friends/Notes	Yes	No
Edit/delete messages	Any message	Bot's own messages only
File upload	Yes	Yes (text, threads, replies)
Thread list	No	Yes (active + archived)
Reaction list	Yes	Yes
Snapshot	Yes	Yes
CI/CD friendly	Requires desktop app	Yes (just set token)

Limitations

• No real-time events in the CLI (real-time Gateway events are available via the SDK — import { DiscordBotListener } from 'agent-messenger/discordbot')
• 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)
• Thread names resolve against active threads only; archived threads need their ID
• thread list --archived returns one page (100 threads) with has_more; no pagination beyond that
• No file download or delete

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:

agent-discordbot message send 1234567890123456789 "Hello"

If the package is NOT installed, use npx -y by default. Do NOT ask the user which package runner to use — just run it:

npx -y agent-messenger discordbot message send 1234567890123456789 "Hello"
bunx agent-messenger discordbot message send 1234567890123456789 "Hello"
pnpm dlx agent-messenger discordbot message send 1234567890123456789 "Hello"

If you already know the user's preferred package runner (e.g., bunx, pnpm dlx), use that instead.

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

For other troubleshooting (permissions, token issues, Message Content Intent), see references/authentication.md.

References

• Authentication Guide
• Common Patterns