Agent Discord

A TypeScript CLI tool that enables AI agents and humans to interact with Discord servers through a simple command interface. Features seamless token extraction from the Discord desktop app and multi-server support.

Quick Start

CODEBLOCK0

Authentication

Credentials are extracted automatically from the Discord desktop app on first use. No manual setup required — just run any command and authentication happens silently in the background.

On macOS, the system may prompt for your Keychain password the first time (required to decrypt Discord's stored token). This is a one-time prompt.

IMPORTANT: NEVER guide the user to open a web browser, use DevTools, or manually copy tokens from a browser. Always use agent-discord auth extract to obtain tokens from the desktop app.

Multi-Server Support

CODEBLOCK1

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, snapshot, etc.)
• After discovering useful channel IDs and names (from channel list, snapshot, etc.)
• After discovering user IDs and names (from user list, user me, etc.)
• After the user gives you an alias or preference ("call this the dev server", "my main channel is X")
• After discovering channel structure (categories, voice channels)

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
• User-given aliases ("dev server", "announcements channel")
• Commonly used thread IDs
• Any user preference expressed during interaction

What NOT to Store

Never store 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

CODEBLOCK2

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

CODEBLOCK3

Message Commands

CODEBLOCK4

Channel Commands

CODEBLOCK5

Server Commands

CODEBLOCK6

User Commands

CODEBLOCK7

DM Commands

CODEBLOCK8

Mention Commands

CODEBLOCK9

Friend Commands

CODEBLOCK10

Note Commands

CODEBLOCK11

Profile Commands

CODEBLOCK12

Member Commands

CODEBLOCK13

Thread Commands

CODEBLOCK14

Reaction Commands

CODEBLOCK15

File Commands

CODEBLOCK16

Snapshot Command

Get comprehensive server state for AI agents:

CODEBLOCK17

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:

CODEBLOCK18

Pretty (Human-Readable)

Use --pretty flag for formatted output:

CODEBLOCK19

Key Differences from Slack

Important: Discord uses Snowflake IDs (large numbers like 1234567890123456789) for all identifiers. You cannot use channel names directly - use channel list to find IDs first.

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
• INLINECODE26 - Monitor channel for new messages
• INLINECODE27 - Generate server summary

Error Handling

All commands return consistent error format:

CODEBLOCK20

Common errors:

• - Not authenticated: No valid token (auto-extraction failed — see Troubleshooting)
• INLINECODE29: Run server switch <id> first
• INLINECODE31: Invalid message ID
• INLINECODE32: Invalid channel ID

Configuration

Credentials stored in: INLINECODE33

Format:
CODEBLOCK21

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

Limitations

• - No real-time events / Gateway connection
• No voice channel support
• No server management (create/delete channels, roles)
• No slash commands
• No webhook support
• Plain text messages only (no embeds in v1)
• User tokens only (no bot tokens)

Troubleshooting

Authentication fails or no token found

Credentials are normally extracted automatically. If auto-extraction fails, run it manually with debug output:

CODEBLOCK22

Common causes:

• - Discord desktop app is not installed or not logged in
• macOS Keychain access was denied (re-run and approve the prompt)
• Discord is not running and LevelDB files are stale

agent-discord: command not found

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

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

CODEBLOCK23

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

CODEBLOCK24

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

References

• - Authentication Guide
• Common Patterns