Discord

Tip: agent-discord is a shortcut for agent-messenger discord.

Quick Start

# 1. Extract credentials from Discord desktop app or browser (zero-config!)
agent-discord auth extract

# 2. Get server snapshot
agent-discord snapshot

# 3. Send a message
agent-discord message send <channel-id> "Hello from AI agent!"

Authentication

Seamless Token Extraction

agent-discord automatically extracts your Discord credentials from the desktop app or Chromium browser:

agent-discord auth extract

# Use --debug for troubleshooting
agent-discord auth extract --debug

# Scan custom Chromium profile/user-data dirs (repeatable or comma-separated)
agent-discord auth extract --browser-profile ~/browser-data
agent-discord auth extract --browser-profile ~/work-profile --browser-profile ~/personal-profile

This command:

Auto-detects your platform (macOS/Linux/Windows)
Extracts Discord user token from the desktop app (with browser fallback)
Validates token against Discord API
Discovers ALL joined servers
Stores credentials securely in ~/.config/agent-messenger/
Supports --browser-profile <path> for agent-browser profiles, custom Chrome user data dirs, or portable browser profiles

Authentication Commands

# Check auth status
agent-discord auth status

# Logout (clear stored credentials)
agent-discord auth logout

Server Management

You must select a server before using most commands.

# List all servers
agent-discord server list

# Switch to a different server
agent-discord server switch <server-id>

# Show current server
agent-discord server current

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

Commands

Whoami Command

# Show current authenticated user
agent-discord whoami
agent-discord whoami --pretty

Output includes the authenticated user's identity information.

Message Commands

# Send a message
agent-discord message send <channel-id> <content>
agent-discord message send 123456789 "Hello world"

# List messages
agent-discord message list <channel-id>
agent-discord message list 123456789 --limit 50

# Get a specific message
agent-discord message get <channel-id> <message-id>

# Delete a message
agent-discord message delete <channel-id> <message-id> --force

# Search messages in current server
agent-discord message search <query>
agent-discord message search "bug fix"

# Search with filters
agent-discord message search "meeting" --channel 123456789
agent-discord message search "report" --author 987654321
agent-discord message search "screenshot" --has image

# Search with sorting and pagination
agent-discord message search "hello" --sort timestamp --sort-dir desc
agent-discord message search "test" --limit 10 --offset 20

Search Options:

--channel <id> - Filter by specific channel
--author <id> - Filter by specific author
--has <type> - Filter by attachment type: file, image, video, embed, link, sticker
--sort <type> - Sort by: timestamp (default), relevance
--sort-dir <dir> - Sort direction: asc, desc (default)
--limit <n> - Number of results (max 25, default 25)
--offset <n> - Pagination offset (default 0)

Note: Search requires a current server to be set. Use agent-discord server switch <server-id> first.

Channel Commands

# List channels in current server
agent-discord channel list

# Get channel info
agent-discord channel info <channel-id>

# Get channel message history
agent-discord channel history <channel-id>
agent-discord channel history 123456789 --limit 100

User Commands

# List server members
agent-discord user list

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

# Get current authenticated user
agent-discord user me

Reaction Commands

# Add reaction
agent-discord reaction add <channel-id> <message-id> <emoji>
agent-discord reaction add 123456789 987654321 thumbsup

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

# List reactions on a message
agent-discord reaction list <channel-id> <message-id>

File Commands

# Upload file to channel
agent-discord file upload <channel-id> <path>
agent-discord file upload 123456789 ./report.pdf

# List files in channel
agent-discord file list <channel-id>

# Get file info
agent-discord file info <channel-id> <file-id>

Snapshot Command

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

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

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

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

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

Default returns brief JSON with:

Server metadata (id, name)
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)

DM Commands

# List DM channels
agent-discord dm list

# Create a DM channel with a user
agent-discord dm create <user-id>

# List unread DM and group-DM channels, newest first
agent-discord dm unread
agent-discord dm unread --limit 10

dm unread covers the DMs that mention unread cannot: Discord's mention history only records guild mentions, so a plain DM never appears there no matter how many unread messages it holds. Instead this compares each DM channel's last_message_id against your per-channel read marker, returning only channels with newer messages.

Each entry carries unread_count, Discord's own badge counter for that channel. In DMs it counts every message rather than only mentions, so it is the number you see on the app's badge. Two values need care:

unread_count: null — the channel has no read-state entry, so the count is unknown. The channel is still reported, because a DM holding messages with no read marker is more likely never opened than read.
unread_count: 0 — the DM is muted. Muting stops the counter but the channel is genuinely unread.

count and total_unread describe every unread DM found, so they stay accurate when --limit caps the returned list. total_unread sums known counts only, so channels with a null count add nothing to it.

complete is false when Discord delivered a partial read state. An absent read-state entry only means "never opened" when the collection is complete, so in a partial payload those channels are omitted rather than reported — which means a never-opened DM can be missing from the result. Treat complete: false as "this list may be short".

Note that dm unread opens a short-lived gateway connection, because Discord exposes read state only through the gateway's READY payload and has no REST equivalent. Expect it to take a few seconds — noticeably longer than dm list.

Thread Commands

# Create a thread in a channel
agent-discord thread create <channel-id> <name>
agent-discord thread create 123456789 "Bug Discussion" --auto-archive-duration 1440

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

Mention Commands

# List recent mentions
agent-discord mention list
agent-discord mention list --limit 10

# Filter by guild
agent-discord mention list --guild <guild-id>

# List only unread mentions (the app's unread-mention badge)
agent-discord mention unread
agent-discord mention unread --guild <guild-id>
agent-discord mention unread --limit 200

mention unread correlates your recent mention history (last 7 days) with Discord's per-channel read state, returning only mentions newer than each channel's read marker. Output includes count (enumerated unread mentions), badge_count (Discord's own account-wide unread-mention badge total — not narrowed by --guild), and complete (whether the scan reached the end of history within the 7-day window). badge_count can exceed count when unread mentions fall outside the 7-day window.

Member Commands

# Search guild members
agent-discord member search <guild-id> <query>
agent-discord member search 123456789 "john" --limit 20

# Get your own membership and roles in a guild
agent-discord member me
agent-discord member me 123456789

member me reads GET /users/@me/guilds/{guild_id}/member, which a user-account token may call for its own membership. Discord's reference lists the guilds.members.read OAuth2 scope for that route; a user-account token is accepted without it, and this was verified against a live account. member search is different: it hits the guild member search endpoint, which requires elevated permissions and answers Missing Access for a user token.

Role names come from GET /guilds/{guild_id}/roles, which any member of the guild may read. Roles are returned highest-first, ordered by position and then by role ID to match Discord's own ordering.

Friend Commands

# List friends and relationships
agent-discord friend list

Profile Commands

# Get a user's profile
agent-discord profile get <user-id>

Note Commands

# Get your note on a user
agent-discord note get <user-id>

# Set a note on a user
agent-discord note set <user-id> "Met at conference"

Global Options

All commands support these options:

--pretty    # Pretty-print JSON output (default is compact JSON)
--server <id>  # Use specific server (overrides current server)

Key Differences from Slack

Concept	Slack	Discord
Server	Workspace	Server
Channel ID	Alphanumeric (C01234567)	Numeric snowflake (123456789012345678)
Message ID	Timestamp (1234567890.123456)	Numeric snowflake (123456789012345678)
User ID	Alphanumeric (U01234567)	Numeric snowflake (123456789012345678)
Threads	Thread timestamps	Thread channels

AI Agent Integration

See skills/agent-discord/ for:

Complete skill documentation
Runnable templates

Discord

On this page