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