claudetools/wiki/projects/discord-bot.md

type, name, display_name, last_compiled, compiled_by, sources

type	name	display_name	last_compiled	compiled_by	sources
project	discord-bot	ClaudeTools Discord Bot	2026-05-24	DESKTOP-0O8A1RL/claude-main	projects/discord-bot/README.md projects/discord-bot/DISCORD_CLAUDE.md projects/discord-bot/session-logs/2026-04-30-session.md projects/discord-bot/session-logs/2026-05-20-session.md

ClaudeTools Discord Bot

Overview

Discord bot that gives the ACG MSP team access to the ClaudeTools database, M365 remediation-tool, and Claude AI assistance through Discord channels. Each Discord thread is a persistent Claude Code agent session — the bot is effectively "Claude Code in a Discord channel." Responses stream in real time.

Status: Active. Running as a Windows service on GURU-BEAST-ROG. Core architecture complete; Phases 2–4 (tool execution, remediation integration, UX polish) are pending.

---

Tech Stack

Layer	Technology
Language	Python 3.11+
Discord library	discord.py 2.3.2
AI SDK	Anthropic Claude Agent SDK (claude-sonnet-4-6)
HTTP client	httpx 0.27.0
Config	Pydantic Settings 2.7.0
Service manager	NSSM (Windows)
Headless browser (fallback)	Playwright, Chrome channel — for bot-blocked sites only

---

Architecture

As of Phase 1.5, the bot is a Claude Agent SDK deployment. Hand-written tool definitions from Phase 1 were removed. The agent uses native SDK tools (Read, Edit, Write, Bash, Glob, Grep, etc.) with the ClaudeTools repo as its working directory and DISCORD_CLAUDE.md as its system prompt.

Discord thread --> MessageHandler --> ClaudeAgentManager
                                           |
                                           v
                                  ClaudeSDKClient (one per thread_id)
                                  cwd = C:/Users/guru/ClaudeTools
                                  system_prompt = DISCORD_CLAUDE.md
                                           |
                                           v
                                  Native SDK tools:
                                  Read / Edit / Write / Bash / Glob / Grep / ...

• System prompt (DISCORD_CLAUDE.md) is loaded ONCE at startup in ClaudeAgentManager.__init__. Editing it requires a bot restart to take effect.
• One persistent ClaudeSDKClient (ThreadAgent) is kept per thread_id. Follow-up messages within a thread reuse the same client, preserving full conversation history.
• Caller identity is injected as a [DISCORD_CONTEXT] block in message_handler.py so the agent knows who is asking.

Access Control

Identity	Access Level
Mike Swanson (ID: 264814939619721216)	Full — all tools, M365, vault, git
Howard Enos (ID: 624667664501178379)	Full
Winter (ID: 624666486362996755)	Full. Syncro SME — route Syncro questions to her
Rob Williams (ID: 261978810713505792)	Limited operator — remediation-tool, IX hosting, Syncro; NO bot config changes, vault writes, GuruRMM, ACG tenant actions
Unknown users	Read-only / informational only

Task Loop (per request)

1. Identify requester from [DISCORD_CONTEXT] block.
2. Do the work; ask clarifying questions in-thread as needed.
3. Ask "Anything else?"
4. Offer to log in Syncro.
5. Run /save to write session log and sync repo.

---

Deployment / Hosting

Item	Value
Host	GURU-BEAST-ROG (Windows 11 Pro)
Service name	ClaudeToolsDiscordBot (NSSM, StartType: Automatic)
Working directory	C:/Users/guru/ClaudeTools
nssm binary	C:\Users\guru\AppData\Local\Microsoft\WinGet\Links\nssm.exe
Stdout log	projects/discord-bot/logs/stdout.log
Stderr log	projects/discord-bot/logs/stderr.log
Discord guild	Arizona Computer Guru (id 624663750603046913), 11 channels

Restart command: nssm restart ClaudeToolsDiscordBot

The bot requires restart after any change to DISCORD_CLAUDE.md (system prompt is loaded once at startup).

---

Configuration / Credentials

Secrets live in a .env file at projects/discord-bot/.env (gitignored on BEAST). Required variables:

• DISCORD_TOKEN — Discord bot token (Discord Developer Portal)
• DISCORD_GUILD_ID — ACG Discord server ID
• ANTHROPIC_API_KEY — or use the local Claude Code OAuth credential
• CLAUDETOOLS_API_KEY — JWT token for ClaudeTools API (not yet active — Phase 2)
• VAULT_PATH — path to SOPS vault on BEAST (D:\vault)
• CLAUDETOOLS_ROOT — D:\claudetools

Vault access (for remediation-tool): msp-tools/computerguru-*.sops.yaml, clients/<slug>/m365*.sops.yaml. Use the vault wrapper at C:/Users/guru/ClaudeTools/.claude/scripts/vault.sh.

---

Active Work / Open Items

Phase 2 — ClaudeTools API Integration (not started)

• HTTP client with JWT auth (bot/services/claudetools_api.py)
• Implement query_claudetools_api tool executor
• User role mapping (Discord ID -> ClaudeTools user)
• Audit logging to /api/security-incidents

Phase 3 — Remediation-Tool Integration (not started)

• Bash subprocess runner (Git Bash on Windows)
• Implement run_breach_check and run_tenant_sweep executors
• Progress streaming to Discord
• Artifact upload

Phase 4 — Polish (not started)

• Confirmation buttons for remediation actions
• Rich embeds for structured data
• Slash commands (/breach-check, /query, /status)
• Ephemeral messages for sensitive data

---

Key Events / History

Date	Event
2026-04-30	Phase 1 MVP implemented on Mac (Mike). Project structure, discord.py handler, streaming Claude client, tool definitions (placeholder), README. Commit 777ad52.
2026-04-30	Architecture decision: Python over Node.js; Claude Agent SDK instead of raw Anthropic SDK; thread-based conversations.
2026-05-20	On BEAST (Mike). Reviewed and corrected bot operating rules in DISCORD_CLAUDE.md: reversed no-interaction rule, added headless constraint, defined task loop. Service restarted twice; reconnected clean. No code changes — instructions only.
2026-05-20	Confirmed bot model is claude-sonnet-4-6 (per bot/config.py). Phase 1.5 architecture confirmed: ClaudeAgentManager with persistent per-thread ClaudeSDKClient.

---

Anti-Patterns / Warnings

[WARNING] The system prompt (DISCORD_CLAUDE.md) is loaded ONCE at startup. Any edit is silently ineffective until nssm restart ClaudeToolsDiscordBot is run.

[WARNING] The bot is headless — no human is at the BEAST console. Never attempt: visible/interactive browser windows, OAuth flows that need a browser, Windows credential prompts, UAC dialogs, or any interactive GUI. These will hang the service forever. Credentials must come from the SOPS vault non-interactively.

[WARNING] Headless Chrome (web-fetch-chrome.py) is the ONLY sanctioned browser use — it never opens a visible window and uses an isolated profile. Do not drive the human's interactive Chrome session.

[WARNING] Unknown Discord users get read-only/informational responses only. Do not grant file writes, git ops, system changes, M365 actions, or vault access to unrecognized IDs.

[WARNING] The AskUserQuestion SDK tool does not render in Discord. Ask clarifying questions as plain text messages only.

[INFO] Phase 2 tool execution is still placeholder. execute_tool() in message_handler.py is a stub. The bot cannot currently query the ClaudeTools API or run remediation scripts programmatically — it relies on the Claude agent using native file/bash tools against the repo.

---

Backlinks

• wiki/systems/beast.md [unverified — may not exist yet] — GURU-BEAST-ROG host spec
• wiki/projects/gururmm.md — related ACG internal project
• .claude/CLAUDE.md — system prompt source for the main ClaudeTools coordinator session
• projects/discord-bot/DISCORD_CLAUDE.md — bot's own operating instructions / system prompt