Claudebot
A Claude Code plugin that turns a Claude Code session into a Discord bot brain with intelligent message triage, tool-based actions, persistent memory, and an organically evolving personality.
How It Works
A runner script (scripts/run-bot.sh) orchestrates the full bot lifecycle:
- Pre-pulls the
claudebot-mcp Docker image and initializes a Claude Code session with this plugin loaded
- Sends periodic poll prompts via
claude -p --resume, maintaining conversation context across cycles
- Claude Code polls Discord for messages via MCP tools and processes them
From there, agents take over — triaging each message, crafting personality-driven replies, running web searches, executing commands, and sending everything directly back to Discord via MCP tools.
Features
- Intelligent triage — Haiku agent evaluates every message: ignore, react, respond, or act
- Direct Discord I/O — Agents send messages, add reactions, and show typing indicators via MCP tools
- Personality system — Starts blank, evolves organically by absorbing traits from chat participants
- Persistent memory — Full context graph (users, topics, relationships) survives context compaction
- Voice screams — Play synthetic screams in voice channels via go-scream Docker integration (6 presets)
- Per-channel configuration — Different channels get different tool permissions and response thresholds
Setup
Prerequisites
- Claude Code CLI installed
- Docker installed and running
- A Discord bot token with message content intent enabled
Install
-
Install the plugin:
claude plugins add /path/to/claudebot
-
Create a .env file in the plugin directory (see .env.example):
CLAUDEBOT_DISCORD_TOKEN=Bot your-bot-token-here
CLAUDEBOT_DISCORD_GUILD_ID=123456789012345678
-
Run the setup command in your project:
/claudebot:bot-setup
-
Start the bot:
./scripts/run-bot.sh
Environment Variables
| Variable | Required | Default | Description |
|---|
CLAUDEBOT_DISCORD_TOKEN | Yes | — | Discord bot token (prefix with Bot ) |
CLAUDEBOT_DISCORD_GUILD_ID | Yes | — | Discord server ID |
CLAUDEBOT_POLL_TIMEOUT | No | 30 | Poll interval in seconds |
CLAUDEBOT_MAX_FAILURES | No | 5 | Max consecutive poll failures before exit |
Configuration
Settings are stored in .claude/claudebot.local.md in your project (not in this plugin repo). See templates/claudebot.local.md for the full template.
Channel Configuration
YAML frontmatter defines per-channel tool permissions and response thresholds:
channels:
general:
tools: [WebSearch, Scream]
respond_threshold: medium
dev:
tools: [WebSearch, Read, Bash, Glob, Grep]
respond_threshold: high
default_channel:
tools: [WebSearch]
respond_threshold: medium
Thresholds: low (direct mentions only), medium (mentions + relevant topics), high (most messages)
Management Commands
/claudebot:bot-setup # Interactive setup wizard
/claudebot:bot-setup show-status # Check MCP connectivity
/claudebot:bot-setup show-config # Show current channel config
/claudebot:bot-setup show-personality # View personality state
/claudebot:bot-setup reset-personality # Reset to blank personality
Architecture
Message Pipeline
Discord → MCP Server (Docker) ←stdio→ Claude Code (-p --resume) ← Runner (poll loop)
↓
Triage Agent (haiku)
↙ ↙ ↘ ↘
ignore react respond act
↓ ↓ ↙ | ↘
emoji responder researcher executor screamer
↓ ↓ ↓ ↓
discord_send_message (via MCP) docker run
Agents
| Agent | Model | Role |
|---|
| triage | haiku | Evaluates every message, routes to downstream agent |
| responder | sonnet | Crafts personality-driven replies |
| researcher | sonnet | Web search, file lookups, information gathering |
| executor | sonnet | Tool-based actions (Bash, file ops) with safety checks |
| screamer | sonnet | Voice channel screams via go-scream Docker container |
| memory-manager | opus | Saves context graph during PreCompact |
| personality-evolver | haiku | Absorbs one user trait per compaction cycle |
Memory System
Memory files live in .claude/memory/ and persist across context compactions:
