@dreki-gg/pi-discord

Discord read tools for pi — pull channel messages and attachments so agents have product context (e.g. a #issues-and-suggestions channel).

Uses Effect for the Discord client layer (typed errors, retries, rate limit handling). Bot-token auth only — automating a user account violates Discord's ToS.

Tools

Tool	Description
discord_list_channels	List text channels in a server (guild) the bot can access
discord_read_messages	Read message history from a channel (oldest-first, paginate with before)
discord_download_attachment	Download an image/file from a message to a temp path

No search tool: Discord's message search is user-account-only and not available to bots.

Setup

1. Create a Discord app + bot

Go to discord.com/developers/applications → New Application → name it (e.g. pi-context).

In the left sidebar → Bot → Reset Token → copy the token → this is your DISCORD_BOT_TOKEN.

2. Enable the Message Content intent (required)

Still on the Bot page → scroll to Privileged Gateway Intents → toggle Message Content Intent ON.

⚠️ Without this, the REST API returns empty content for every message. For a bot in fewer than 100 servers this toggle needs no Discord verification.

3. Invite the bot to your server

Left sidebar → OAuth2 → URL Generator:

• Scopes: bot
• Bot Permissions: View Channels, Read Message History

Copy the generated URL, open it, pick your server, authorize. (You need Manage Server permission on that server, or ask an admin.)

4. Get guild + channel IDs

In the Discord client → Settings → Advanced → Developer Mode ON. Then right-click a server → Copy Server ID (guild), and right-click a channel → Copy Channel ID.

5. Set the token

export DISCORD_BOT_TOKEN="your-bot-token"

Project config (.pi/discord.json)

All fields optional:

{
  "defaultGuild": "123456789012345678",
  "defaultChannel": "234567890123456789",
  "messageLimit": 50
}

• defaultGuild — used by discord_list_channels when you don't pass guild.
• defaultChannel — informational (shown in /discord status).
• messageLimit — default page size for discord_read_messages (1-100, default 50).

Commands

• /discord — show token + config status.

Notes

• IDs are numeric snowflakes.
• The bot only sees servers it's invited to and channels where it has View Channel + Read Message History.
• discord_read_messages returns newest-first from Discord but is formatted oldest-first; use the returned oldestId as before to page further back.
• Attachment URLs are public Discord CDN links — discord_download_attachment fetches them without auth.