Aufhocker Discord Bot

Aufhocker is a Discord bot that integrates with Claude AI, providing AI assistance directly within Discord servers using conversation history as context.

Features

• Claude AI Integration: Interact with Claude AI through Discord slash commands
• Private Responses by Default: All responses are private to you initially for privacy
• Make Public Button: Share responses with everyone using the "📢 Make Public" button
• Secure Sharing: Only you can make your responses public, with 1-hour expiry for security
• Conversation Context: Uses server message history to provide relevant context to Claude
• Configurable Context: Users can specify context scope (message count or time duration)
• Configurable Message Retention: Automatically stores and prunes message history (default 30 days, via RETENTION_DAYS)
• Admin Tools (opt-in): With ENABLE_ADMIN_TOOLS, Claude can use web_search (Brave) and web_fetch (SSRF-guarded) for admin users
• Rate Limiting: Built-in per-user rate limiting with admin bypass capabilities
• Admin Emergency Controls: Temporary bypasses, rate limit management, and audit trail via the /aufadmin command
• Optional Plugins: League of Legends live-game monitor/predictions and a Diablo 2 (d2emu) terror-zone / DClone tracker — both off by default
• Comprehensive Logging: Detailed logging for debugging and monitoring

Quick Start

Prerequisites

• Node.js 22.0.0 or higher
• PostgreSQL database (or use the bundled Docker Compose stack)
• Discord Bot Token
• Claude API Key

Installation

1. Clone the repository:

git clone <repository-url>
cd aufhocker

2. Install dependencies:

npm install

3. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

4. Set up the database:

# Create database and run migrations
npm run db:migrate

5. Build and start the bot:

npm run build
npm start

For development:

npm run dev

Local Development with Docker

For a quick local development setup using Docker:

1. Start PostgreSQL and pgAdmin:

docker-compose up -d

2. Access the services:

   • PostgreSQL: localhost:5432
   • pgAdmin: http://localhost:5050
     • Email: admin@aufhocker.local
     • Password: admin

3. The database is automatically initialized with the required schema.

4. To stop the services:

docker-compose down

5. To reset the database (removes all data):

docker-compose down -v
docker-compose up -d

Docker Environment Variables

The following environment variables can be customized in your .env file for Docker:

Variable	Default	Description
POSTGRES_USER	aufhocker	PostgreSQL username
POSTGRES_PASSWORD	aufhocker_dev	PostgreSQL password
POSTGRES_DB	aufhocker	Database name
POSTGRES_PORT	5432	PostgreSQL port
PGADMIN_EMAIL	admin@aufhocker.local	pgAdmin login email
PGADMIN_PASSWORD	admin	pgAdmin login password
PGADMIN_PORT	5050	pgAdmin web interface port

Configuration

Configuration is split across two files so secrets and non-secret tuning have different lifecycles:

• .env (git-ignored) — secrets and deployment identity only. Copy .env.example to .env and fill it in.
• .env.config (committed) — non-secret defaults: models, intervals, feature flags, pool sizes. Edit this for behaviour changes; it contains no credentials.

Both are loaded together (docker-compose env_file: [.env.config, .env]; local runs load .env then .env.config via dotenv). Their keys are disjoint, and a value in .env wins on any overlap. .env.development / .env.production remain full single-file templates for setups that prefer one file.

Required Configuration

• DISCORD_TOKEN: Your Discord bot token
• DISCORD_CLIENT_ID: Your Discord application client ID
• CLAUDE_API_KEY: Your Anthropic Claude API key
• DATABASE_URL: PostgreSQL connection string

Optional Configuration

• CLAUDE_MODEL: Claude model to use (default: claude-sonnet-5)
• CLAUDE_MAX_TOKENS: Maximum tokens per request (default: 4096)
• CLAUDE_MAX_CONTEXT_TOKENS: Token budget for channel-history context sent to Claude (default: 3000)
• RETENTION_DAYS: Message retention period in days (default: 30)
• ENABLE_ADMIN_TOOLS: Enable Claude tool use (web_search/web_fetch) for admin users (default: false; web_search also needs BRAVE_SEARCH_API_KEY)
• LOG_LEVEL: Logging level (default: info)

Usage

Basic Commands

• /aufhocker query:<your question> - Ask Claude a question privately (default: last 1 hour context)
• /aufhocker query:<your question> context:20 messages - Ask with specific message count context
• /aufhocker query:<your question> context:1 hour - Ask with time-based context
• /aufhocker query:<your question> context:24 hours - Ask with extended time context

Context Parameter (Optional)

The context parameter is optional and controls how much conversation history Claude sees:

When omitted: Defaults to the last 1 hour of messages Message count: context:20 messages or context:50 (1-100 messages) Time duration: context:2 hours or context:3 days (1-23 hours, 1-30 days) Relative dates: context:yesterday or context:today Specific dates: context:2026-01-10 (ISO format, all times in UTC)

💡 Tip: For simple questions, leave context empty to use the default (last 1 hour).

Privacy & Sharing

🔒 Private by Default: All responses are initially private - only you can see them.

📢 Make Public: Use the "Make Public" button to share responses with everyone in the channel.

🛡️ Security Features:

• Only the original user can make their response public
• Public sharing expires after 1 hour for security
• Context from channel history is always used appropriately

Examples

/aufhocker query:What's the main topic we've been discussing?
/aufhocker query:Can you summarize what John said? context:10 messages
/aufhocker query:What decisions did we make about the project? context:2 hours
/aufhocker query:What was discussed yesterday? context:yesterday
/aufhocker query:What happened on this date? context:2026-01-10

Workflow:

1. Use /aufhocker query:<your question> command
2. Optionally add context: parameter to specify conversation history scope
3. Receive a private response with Claude's answer
4. Optionally click "📢 Make Public" to share with everyone
5. Public responses expire after 1 hour automatically

Privacy & Security

Aufhocker is designed with privacy and security in mind:

Private Responses by Default

• All Claude responses are ephemeral (private) by default
• Only the user who asked the question can see the initial response
• This prevents accidental sharing of sensitive information

Controlled Public Sharing

• Users can choose to make responses public using the "📢 Make Public" button
• Security: Only the original user can make their own response public
• Expiry: Public sharing capability expires after 1 hour for security
• One-time: Each response can only be made public once

Context Privacy

• Message history is used appropriately for context
• Bot messages are excluded from context to prevent confusion
• Context is channel-specific (no cross-channel data leakage)
• Automatic retention policy (default 30 days, configurable via RETENTION_DAYS) protects long-term privacy

Technical Security Features

• Response IDs include user verification to prevent unauthorized sharing
• Automatic cleanup of expired sharing tokens
• Secure button interaction handling with user validation
• Comprehensive error handling to prevent information leakage

Development

Scripts

• npm run build - Build TypeScript to JavaScript
• npm run dev - Run in development mode with hot reload
• npm test - Run all tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage report
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint issues automatically

Testing

The project includes comprehensive testing:

• Unit Tests: Test individual components in isolation
• Property-Based Tests: Validate universal correctness properties
• Integration Tests: Test component interactions

Run tests:

npm test

Project Structure

src/
├── admin/         # Admin domain: AdminService, RateLimiter, AdminAuditService, UserMapper
├── bot/           # Thin host (AufhockerBot): infra + plugin registry dispatch
├── claude/        # Anthropic SDK client, tool executor, SSRF guard, ToolAuditService
├── commands/      # Slash-command parsing + admin command handling
├── config/        # Configuration management
├── context/       # Channel history → Claude context assembly
├── database/      # Postgres connection, message store, migrations
├── discord/       # Discord client, command registration, routing
├── message/       # Message processing and 2000-char splitting
├── plugins/       # Plugin contract + features: query/ (core chat), lol/, d2emu/
├── types/         # Shared TypeScript type definitions
├── utils/         # Cross-cutting infra only: logger, ErrorHandler, ShutdownHandler
└── test/          # Test setup and utilities

Database Schema

The bot uses PostgreSQL. Migrations under src/database/migrations/scripts/ are the single source of truth; they are applied automatically at startup. Core tables:

• messages — message history (pruned per RETENTION_DAYS, default 30)
• user_mappings — Discord-ID → display-name mappings
• admin_audit_trail — audit log of all admin actions
• temporary_rate_limit_bypasses — active/expired admin-granted bypasses
• schema_migrations — applied-migration bookkeeping

Plugin tables (created only by their migrations): lol_watchlist, lol_active_games, lol_monitor_config, lol_prediction_history, d2emu_config.

Error Handling

The bot includes comprehensive error handling for:

• Authentication failures (Discord/Claude)
• Rate limiting (with exponential backoff)
• Network errors (with retry logic)
• Database connection issues
• Invalid command parameters

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Deployment

For detailed deployment instructions, see the Deployment Guide:

• Local Development: Docker Compose setup with PostgreSQL and pgAdmin
• Production: Docker Swarm — registry-pulled image, shared Postgres, Swarm secrets (the live deployment)
• Alternative: single-host self-contained stack via docker-compose.production.yml
• Database Migrations: Schema management and updates
• Troubleshooting: Common issues and solutions

Quick links:

• Local Development Setup
• Production Deployment (Docker Swarm)
• Troubleshooting Guide

Admin Controls

For global administrators, Aufhocker provides emergency controls and administrative features through the separate /aufadmin command. See the Admin Controls Guide for details:

• Separate Admin Command: /aufadmin command with Discord Administrator permission requirement
• Dual Permission System: Requires both Discord Administrator role AND global admin user ID configuration
• Temporary Rate Limit Bypasses: Grant temporary relief to users
• Rate Limit Management: Clear rate limits for users or all users
• Status Monitoring: Check rate limit status for any user
• Audit Trail: All admin actions are logged for security and compliance

Admin Commands

Important: Admin commands require both Discord Administrator permission AND being configured as a global admin in the bot settings.

• /aufadmin quota bypass - Grant temporary rate limit bypass to a user
• /aufadmin quota revoke - Revoke temporary bypass for a user
• /aufadmin quota status - Check user rate limit status
• /aufadmin quota clear - Clear rate limits for a user or all users
• /aufadmin reload-mappings - Re-read user-mappings.json and sync it to the database

Visibility: Non-admin users will not see the /aufadmin command in their command list. Only users with Discord Administrator role will see it, but execution still requires global admin user ID configuration.

Quick links:

• Admin Configuration
• Admin Commands
• Security Considerations
• Troubleshooting

Support

For issues and questions:

1. Check the logs in the logs/ directory
2. Review the Deployment Guide troubleshooting section
3. Ensure all required environment variables are set
4. Check database connectivity

Security

• Never commit your .env file
• Rotate API keys regularly
• Use environment-specific configurations
• Monitor usage and rate limits