claudetools/projects/discord-bot

ClaudeTools Discord Bot

Discord bot providing MSP team access to ClaudeTools database, M365 remediation-tool, and Claude AI assistance through Discord channels.

Features

• Conversational AI: Powered by Claude API with full context awareness
• ClaudeTools Integration: Query MSP database (clients, sessions, tasks, infrastructure)
• M365 Security: Run breach checks and tenant sweeps via remediation-tool
• Thread-Based: Isolated conversations with full history
• Streaming Responses: Real-time updates as Claude thinks and executes tools

Architecture

As of Phase 1.5, the bot is "Claude Code in a Discord channel." Each Discord thread is a persistent ClaudeSDKClient session whose cwd is the ClaudeTools repo root, with .claude/CLAUDE.md as the system prompt. The agent uses the Claude Agent SDK's native tools (Read, Edit, Write, Bash, Glob, Grep, etc.) — the bot does not hand-write tool definitions or call the ClaudeTools HTTP API.

Discord thread  ──>  MessageHandler  ──>  ClaudeAgentManager
                                                │
                                                v
                                       ClaudeSDKClient (per thread)
                                       cwd = ClaudeTools repo
                                       system_prompt = .claude/CLAUDE.md
                                                │
                                                v
                                       Native SDK tools:
                                       Read / Edit / Write / Bash / Glob / Grep / ...

Prerequisites

• Python 3.11+
• Discord Bot created in Discord Developer Portal
• Anthropic API Key for Claude access
• ClaudeTools API running at http://172.16.3.30:8001
• Git Bash (Windows) for remediation-tool scripts
• SOPS Vault accessible at D:\vault (Windows) or configured path

Setup

1. Discord Bot Setup

1. Go to Discord Developer Portal
2. Create New Application
3. Go to "Bot" section
4. Click "Add Bot"
5. Enable these Privileged Gateway Intents:
   • Message Content Intent
   • Server Members Intent
6. Copy the bot token
7. Go to "OAuth2" → "URL Generator"
8. Select scopes: bot, applications.commands
9. Select bot permissions:
   • Send Messages
   • Send Messages in Threads
   • Create Public Threads
   • Read Message History
   • Use Slash Commands
10. Copy the generated URL and invite bot to your server

2. Environment Configuration

1. Copy .env.example to .env:

   cp .env.example .env
   

2. Edit .env and fill in your values:

   DISCORD_TOKEN=your_bot_token_from_step_1
   DISCORD_GUILD_ID=your_server_id
   ANTHROPIC_API_KEY=your_anthropic_key
   CLAUDETOOLS_API_KEY=your_api_key
   
   # Windows paths (adjust for your system)
   VAULT_PATH=D:\vault
   CLAUDETOOLS_ROOT=D:\claudetools
   

3. Install Dependencies

pip install -r requirements.txt

Running the Bot

Development (Command Line)

cd projects/discord-bot
python -m bot.main

Production (Windows Service with NSSM)

1. Download NSSM

2. Install as service:

   nssm install ClaudeToolsDiscordBot "C:\Python311\python.exe" "-m bot.main"
   nssm set ClaudeToolsDiscordBot AppDirectory "D:\claudetools\projects\discord-bot"
   nssm set ClaudeToolsDiscordBot Start SERVICE_AUTO_START
   nssm set ClaudeToolsDiscordBot AppStdout "D:\claudetools\projects\discord-bot\logs\stdout.log"
   nssm set ClaudeToolsDiscordBot AppStderr "D:\claudetools\projects\discord-bot\logs\stderr.log"
   

3. Start service:

   nssm start ClaudeToolsDiscordBot
   

4. Check status:

   nssm status ClaudeToolsDiscordBot
   

Usage

Mention-Based Conversations

Start a conversation by mentioning the bot:

@ClaudeTools hello!
@ClaudeTools list clients from last week
@ClaudeTools check john.trozzi@cascadestucson.com for breach

The bot will:

1. Create a dedicated thread for the conversation
2. Stream Claude's response with live updates
3. Execute tools as needed (database queries, breach checks)
4. Maintain full conversation context

Example Queries

ClaudeTools Database:

@ClaudeTools show me GuruRMM sessions from April
@ClaudeTools list all Cascades tickets
@ClaudeTools what infrastructure do we manage for Dataforth?

M365 Breach Checks:

@ClaudeTools check user@domain.com for breach
@ClaudeTools sweep cascadestucson.com tenant for security issues

General Questions:

@ClaudeTools what projects are we working on?
@ClaudeTools summarize work from yesterday

Project Structure

discord-bot/
├── bot/
│   ├── main.py                  # Entry point
│   ├── config.py                # Configuration
│   ├── handlers/
│   │   └── message_handler.py   # Discord message handling
│   ├── claude/
│   │   ├── client.py            # Claude API wrapper
│   │   └── tools.py             # Tool definitions
│   ├── services/               # (Phase 2) ClaudeTools API client
│   ├── auth/                   # (Phase 2) User permissions
│   └── formatting/             # (Phase 4) Embeds and tables
├── .env                        # Environment config (gitignored)
├── .env.example                # Template
├── requirements.txt
└── README.md

Development Roadmap

Phase 1.5: Claude Agent SDK refactor (Current)

• Discord bot connection
• Claude Agent SDK streaming (replaces raw Anthropic SDK)
• Per-thread persistent agent sessions (ClaudeSDKClient)
• Workspace = ClaudeTools repo; system prompt = .claude/CLAUDE.md
• Native SDK tools (Read/Edit/Write/Bash/Glob/Grep) — no hand-written tools
• The hand-written query_claudetools_api, run_breach_check, and run_tenant_sweep tools from the Phase 1 scaffold were removed. The agent invokes those workflows via the existing skills under .claude/skills/ and via Bash + the vault wrapper, the same way Claude Code does.

Phase 2: ClaudeTools API Integration

• HTTP client with JWT auth
• Implement query_claudetools_api tool
• User role mapping (admin vs tech)
• Audit logging

Phase 3: Remediation-Tool Integration

• Bash subprocess runner
• Implement run_breach_check tool
• Implement run_tenant_sweep tool
• Progress streaming
• Artifact upload

Phase 4: Polish

• Confirmation buttons for remediation
• Rich embeds for structured data
• Select menus for multi-choice
• Ephemeral messages for sensitive data
• Slash commands

Troubleshooting

Bot doesn't respond to mentions

1. Check bot is online: Look for green status in Discord
2. Check intents: Message Content Intent must be enabled in Discord Developer Portal
3. Check logs: tail -f logs/bot.log
4. Verify permissions: Bot needs "Send Messages" and "Send Messages in Threads"

Path validation errors

FileNotFoundError: Vault not found at D:\vault

Fix: Update VAULT_PATH in .env to match your system.

Module import errors

ModuleNotFoundError: No module named 'discord'

Fix: Install dependencies: pip install -r requirements.txt

Contributing

This is Phase 1 MVP. Next steps:

1. Implement tool execution (see bot/handlers/message_handler.py execute_tool placeholder)
2. Add ClaudeTools API client (see bot/services/)
3. Add remediation script runner (see bot/services/)

License

Internal Arizona Computer Guru project.