GitHub - dOrgTech/discord_support_agent: AI-powered Discord support bot that uses Claude to answer user questions from searchable local documentation. Creates threaded conversations, shows live progress, rate-limits usage, and escalates to humans when needed.

Support Agent

AI-powered Discord support bot that uses Claude to answer user questions, backed by searchable local documentation.

Built for Tezos Homebase but designed to be reusable for any project with documentation repos.

How it works

A user with the required role posts a question in the designated Discord channel.
The bot creates a thread from that message for an isolated support conversation.
Claude receives the question along with tools to search, read, and list files from local documentation repos.
A live status embed shows what the bot is doing (thinking, searching docs, reading files).
The final answer replaces the embed in the thread.
Follow-up messages in the same thread continue the conversation with full history.

If Claude can't resolve the issue, it can escalate by pinging a human in the thread.

Features

Threaded conversations -- each question gets its own Discord thread with isolated history
Tool-assisted answers -- Claude searches and reads documentation to give accurate responses
Live status embeds -- users see what the bot is doing while it investigates
Rate limiting -- rolling 24h window per user with configurable limits
Escalation -- bot can ping a human when it's stuck
Message deduplication -- guards against Discord firing duplicate events
Configurable -- all settings via environment variables, no hardcoded secrets

Setup

Prerequisites

Python 3.11+
A Discord bot with Message Content and Server Members intents enabled
ATN bridge provider for Claude access
Documentation repos cloned into docs/

Installation

git clone <this-repo>
cd support_agent

pip install -r requirements.txt

# Clone your documentation repos
git clone --depth 1 https://github.com/dOrgTech/homebase-app docs/homebase-app
git clone --depth 1 https://github.com/tezos-commons/baseDAO docs/baseDAO

# Configure
cp .env.example .env
# Edit .env with your values

Configuration

Copy .env.example to .env and fill in the values. See the file for descriptions of each variable.

Key settings:

Variable	Description
`DISCORD_BOT_TOKEN`	Bot token from Discord Developer Portal
`DISCORD_CHANNEL_ID`	Channel where the bot listens for new questions
`DISCORD_REQUIRED_ROLE`	Role name required to interact with the bot
`ESCALATION_USER_ID`	Discord user ID to ping on escalation
`ATN_PATH`	Path to the ATN bridge provider package
`DOC_REPOS`	Comma-separated repo directory names under `DOCS_ROOT`

Running

Running as a service

Linux (systemd)

# /etc/systemd/system/support-agent.service
[Unit]
Description=Support Agent Discord Bot
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/support_agent
ExecStart=/home/ubuntu/support_agent/.venv/bin/python bot.py
Restart=always
RestartSec=10
EnvironmentFile=/home/ubuntu/support_agent/.env

[Install]
WantedBy=multi-user.target

sudo systemctl enable support-agent
sudo systemctl start support-agent

Windows (Task Scheduler)

A setup script is provided:

powershell -ExecutionPolicy Bypass -File setup_task.ps1

This creates a scheduled task that runs bot.py at system startup.

Architecture

bot.py          -- single-file bot: Discord client, tool implementations,
                   status embeds, rate limiting, thread state management
docs/           -- cloned documentation repos (gitignored)
.env            -- configuration (gitignored)
.env.example    -- configuration template

The bot is intentionally a single file. It has two runtime dependencies (discord.py and python-dotenv) plus the ATN bridge provider for Claude access.

License

MIT