Discord Bot Setup: Add PocketPaw to Your Server

PocketPaw integrates with Discord via discli (Discord CLI agent). It supports slash commands, direct messages, @mention in channels, and full server management through an MCP-based tool layer that works across all agent backends.

Setup

export POCKETPAW_DISCORD_BOT_TOKEN="your-discord-token"

pocketpaw --discord

Configuration

Features

Slash Command

The bot registers a /paw slash command. Users can interact with:

/paw What files are in the home directory?

DM and Mention Support

• Direct messages — Send a DM to the bot for private conversations
• @mention — Mention the bot in any channel where it’s present

Streaming

Discord supports edit-in-place streaming with a 1.5-second rate limit. The bot sends an initial message and edits it as tokens arrive, batching updates to respect Discord’s rate limits.

Access Control

# Restrict to specific servers
export POCKETPAW_DISCORD_ALLOWED_GUILD_IDS="111222333,444555666"

# Restrict to specific users
export POCKETPAW_DISCORD_ALLOWED_USER_IDS="777888999"

Conversation Mode

Conversation mode lets the bot participate naturally in group channels without requiring explicit mentions or slash commands.

When enabled for a channel, the bot:

• Tracks recent messages in a rolling 30-message window
• Decides when to respond based on context: responds when addressed by name, when it’s part of an active conversation, or when someone asks a question while it’s recently active
• Stays silent when appropriate by returning a [NO_RESPONSE] marker that the adapter suppresses, allowing natural “lurking”
• Injects conversation context from the last 30 messages (up to 12,000 characters) into the agent prompt for natural, context-aware replies

Per-channel: Use the /converse slash command in any channel (requires Administrator or Manage Server permission). Run it again to toggle off.

Server-wide: Enable conversation mode across all channels at once via environment variable:

export POCKETPAW_DISCORD_CONVERSATION_ALL_CHANNELS=true

# Optionally exclude specific channels (e.g. announcements, rules)
export POCKETPAW_DISCORD_CONVERSATION_EXCLUDE_CHANNEL_IDS="123456789,987654321"

Idle channels are automatically cleaned up after 1 hour of inactivity.

Bot Presence

Customize the bot’s online status and activity in Discord:

export POCKETPAW_DISCORD_STATUS_TYPE=online        # online, idle, dnd, invisible
export POCKETPAW_DISCORD_ACTIVITY_TYPE=watching     # playing, streaming, listening, watching
export POCKETPAW_DISCORD_ACTIVITY_TEXT="your code"

This shows the bot as “Watching your code” in the member list.

Slash Commands

Kill Command

Send /kill or !kill in any channel to cancel the currently running agent task for that session. This is useful when a response is taking too long or the agent is stuck. The kill command works across all channels (Discord, Telegram, Slack, WhatsApp, and the web dashboard).

Discord MCP Server

When the Discord adapter starts, it auto-registers a pocketpaw-discord MCP server. This exposes Discord operations (send messages, create polls, manage roles, etc.) as native MCP tools available to any backend — including codex_cli, google_adk, and claude_agent_sdk.

The MCP server wraps the discli CLI and provides structured tools like discord_send_message, discord_create_poll, discord_add_reaction, etc. Backends don’t need special Discord integration; they just call MCP tools.

The server config is saved to ~/.pocketpaw/mcp_servers.json and persists across restarts.

Docker Deployment

A dedicated Discord Docker setup is available for running the bot in a container. See the Discord Docker Deployment guide for the full walkthrough, including Claude Code OAuth support and Coolify-friendly configuration.

Quick start:

cd deploy/discord
cp .env.example .env
# Edit .env with your bot token and LLM provider
docker compose up -d

Installation

curl -fsSL https://pocketpaw.xyz/install.sh | sh

# Or add the Discord extra manually
pip install pocketpaw[discord]

This installs discord-cli-agent as an optional dependency.

Related