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

1. A user with the required role posts a question in the designated Discord channel.
2. The bot creates a thread from that message for an isolated support conversation.
3. Claude receives the question along with tools to search, read, and list files from local documentation repos.
4. A live status embed shows what the bot is doing (thinking, searching docs, reading files).
5. The final answer replaces the embed in the thread.
6. 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

python bot.py

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