Agent Discord

Interact with Discord servers - send messages, read channels, manage reactions

Security Scan

The skill's functionality (controlling a user's Discord account) is coherent with its files and scripts, but it omits and normalizes sensitive local credential access (automatic token extraction, plaintext credential storage, and mandated reading/writing of a persistent memory file) without declaring those config paths or making provenance clear — this mismatch and the implicit credential handling are concerning.

Purpose & Capability

The skill's stated purpose (interact with Discord as the user) legitimately requires a user token and a CLI like agent-discord. However the registry metadata claims no required config paths or credentials while the SKILL.md and references explicitly instruct locating the Discord desktop app data, extracting the user token from LevelDB, and storing credentials at ~/.config/agent-messenger/discord-credentials.json — this undeclared local-file/credential access is an incoherence that reduces transparency.

Instruction Scope

SKILL.md and references explicitly instruct the tool/agent to extract tokens from the Discord desktop app (LevelDB Local Storage), to read a persistent memory file (~/.config/agent-messenger/MEMORY.md) at the start of every task using agent tools, and to write persistent memory. Those instructions involve accessing sensitive local files and credentials and directing the agent to read/write persistent state every run; this scope is broader than the registry metadata declares and contains potentially sensitive operations (automatic silent extraction).

Install Mechanism

Install spec is a Node package (agent-messenger) that provides the agent-discord binary — using npm is expected for a CLI. The package is not pinned to a specific verified source in metadata and provenance isn't provided; installing an unpinned npm package from an unknown owner increases supply-chain risk and should be audited before installation.

Credentials

The skill requests no environment variables, but it extracts and stores the user's Discord user token (sensitive credential) from local application storage and writes it plaintext to ~/.config/agent-messenger/discord-credentials.json. Storing user tokens in plaintext and performing automatic extraction without explicit declared config/credential requirements is disproportionate without clear user consent and provenance. The SKILL.md warns not to store tokens in memory files, but the tool itself will store them on disk.

Persistence & Privilege

The skill does not request always:true and is not set to be omnipresent, which is good. However it instructs the agent to maintain a persistent memory file and to read it at the start of every task; that persistent local state is not declared in the registry config paths. The combination (persistent local files + credential storage) increases blast radius if the package or CLI is compromised.

What to consider before installing

This skill will extract your Discord user token from the desktop app and store it in ~/.config/agent-messenger/discord-credentials.json (plaintext), and it expects to read/write a persistent memory file (~/.config/agent-messenger/MEMORY.md) every run. Before installing or running it: 1) verify the package source (agent-messenger) and review its code on a trusted repo or npm page; 2) prefer using a bot token with scoped permissions rather than a user token (self-bots may violate Discord ToS); 3) if you proceed, run in an isolated account or VM, audit what the CLI writes under ~/.config, and ensure the credentials file is protected (chmod 600) and removed if you revoke access; 4) ask the publisher why config/credential paths are not declared in registry metadata and request a reproducible install provenance (package version, repository URL). The current mismatch between instructions and declared metadata is the main reason for caution.

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

# Get server snapshot (credentials are extracted automatically)
agent-discord snapshot

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

# List channels
agent-discord channel list

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

# List all available servers
agent-discord server list

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

# Show current server
agent-discord server current

# Check auth status
agent-discord auth status

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

# Agent Messenger Memory

## Discord Servers

- `1234567890123456` — Acme Dev (default)
- `9876543210987654` — Open Source Community

## 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

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

## Notes

- User prefers --pretty output for snapshots
- Main server is "Acme Dev"

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

# Extract token from Discord desktop app (usually automatic)
agent-discord auth extract
agent-discord auth extract --debug

# Check auth status
agent-discord auth status

# Logout from Discord
agent-discord auth logout

Message Commands

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

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

# Get a single message by ID
agent-discord message get <channel-id> <message-id>
agent-discord message get 1234567890123456789 9876543210987654321

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

# Acknowledge/mark a message as read
agent-discord message ack <channel-id> <message-id>

# Search messages in current server
agent-discord message search <query>
agent-discord message search "project update" --limit 10
agent-discord message search "hello" --channel <channel-id> --author <user-id>

Channel Commands

# List channels in current server (text channels only)
agent-discord channel list

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

# Get channel history (alias for message list)
agent-discord channel history <channel-id> --limit 100

Server Commands

# List all servers
agent-discord server list

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

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

# Show current server
agent-discord server current

User Commands

# List server members
agent-discord user list

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

# Get current user
agent-discord user me

DM Commands

# List DM channels
agent-discord dm list

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

Mention Commands

# List recent mentions
agent-discord mention list
agent-discord mention list --limit 50
agent-discord mention list --guild <server-id>

Friend Commands

# List all relationships (friends, blocked, pending requests)
agent-discord friend list
agent-discord friend list --pretty

Note Commands

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

# Set note for a user
agent-discord note set <user-id> "Note content"

Profile Commands

# Get detailed user profile
agent-discord profile get <user-id>

Member Commands

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

Thread Commands

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

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

Reaction Commands

# Add reaction (use emoji name without colons)
agent-discord reaction add <channel-id> <message-id> <emoji>
agent-discord reaction add 1234567890123456789 9876543210987654321 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
agent-discord file upload <channel-id> <path>
agent-discord file upload 1234567890123456789 ./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 comprehensive server state for AI agents:

# Full snapshot
agent-discord snapshot

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

# Limit messages per channel
agent-discord snapshot --limit 10

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:

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

Pretty (Human-Readable)

Use --pretty flag for formatted output:

agent-discord channel list --pretty

Key Differences from Slack

Feature	Discord	Slack
Server terminology	Server	Workspace
Channel identifiers	Snowflake IDs	Channel name or ID
Message identifiers	Snowflake IDs	Timestamps (ts)
Threads	Thread ID field	Thread timestamp
Mentions	<@user_id>	<@USER_ID>

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

Error Handling

All commands return consistent error format:

{
  "error": "Not authenticated. Run \"auth extract\" first."
}

Common errors:

• Not authenticated: No valid token (auto-extraction failed — see Troubleshooting)
• No current server set: Run server switch <id> first
• Message not found: Invalid message ID
• Unknown Channel: Invalid channel ID

Configuration

Credentials stored in: ~/.config/agent-messenger/discord-credentials.json

Format:

{
  "token": "user_token_here",
  "current_server": "1234567890123456789",
  "servers": {
    "1234567890123456789": {
      "server_id": "1234567890123456789",
      "server_name": "My Server"
    }
  }
}

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:

agent-discord auth extract --debug

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:

agent-discord server list

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

bunx agent-messenger discord server list

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