Claude Discord Coordinator

A production-ready Discord bot that routes per-channel messages to persistent Claude Code CLI sessions, providing each Discord channel with its own AI assistant context.

Status: Production-ready • 13/18 tasks complete (72%) • 156/157 tests passing (99.4%)

🎯 What It Does

• Routes Discord messages to Claude CLI with persistent sessions
• Each channel maintains separate conversation history
• Sessions survive bot restarts (SQLite persistence)
• Intelligent response formatting for Discord (2000-char chunks, code blocks)
• Slash commands for session management
• Production-grade logging and error reporting

✨ Features

Core Functionality

• ✅ Channel-based routing: @mention bot in configured channels
• ✅ Session persistence: SQLite database stores session_id per channel
• ✅ Context preservation: Claude remembers conversation history
• ✅ Response formatting: Smart chunking, code block preservation
• ✅ Concurrent handling: Per-channel locking prevents race conditions

Slash Commands

/reset [channel]  - Clear session and start fresh (requires manage_messages)
/status           - Show all active sessions with stats
/model <name>     - Switch Claude model (Sonnet/Opus/Haiku)

Operational Features

• ✅ Persistent typing indicator: Shows for long operations (30s-5min)
• ✅ Structured JSON logging: 10MB rotation, 5 backup files
• ✅ Error tracking: Unique error IDs for support
• ✅ Privacy-safe errors: Internal details hidden from Discord users
• ✅ Performance metrics: Duration, cost, session stats tracked

📁 Project Structure

claude-coordinator/
├── claude_coordinator/
│   ├── bot.py                  # Main Discord bot (244 lines)
│   ├── commands.py             # Slash commands (411 lines)
│   ├── response_formatter.py   # Message formatting (329 lines)
│   ├── claude_runner.py        # CLI subprocess wrapper (296 lines)
│   ├── session_manager.py      # SQLite persistence (486 lines)
│   ├── config.py               # YAML configuration (300 lines)
│   └── logging_config.py       # Structured logging (371 lines)
├── tests/
│   ├── test_bot.py             # 27 tests
│   ├── test_commands.py        # 18 tests
│   ├── test_response_formatter.py  # 26 tests
│   ├── test_claude_runner.py   # 11 tests
│   ├── test_session_manager.py # 27 tests
│   ├── test_config.py          # 25 tests
│   ├── test_concurrency.py     # 7 tests
│   └── test_logging.py         # 15 tests
├── docs/
│   ├── BOT_USAGE.md            # Complete usage guide
│   ├── COMMANDS_USAGE.md       # Slash command documentation
│   ├── LOGGING.md              # Logging system details
│   └── *.md                    # Implementation notes
├── config.example.yaml         # Example configuration
└── pyproject.toml              # uv project configuration

🚀 Quick Start

Prerequisites

• Python 3.12+
• Claude CLI authenticated (as discord-bot user)
• Discord bot token

Installation

cd /opt/projects/claude-coordinator
source .venv/bin/activate  # Already created with uv

Configuration

Create config.yaml:

discord:
  token: "your-discord-bot-token"  # Or use DISCORD_TOKEN env var

projects:
  - name: "my-project"
    channel_id: "123456789012345678"
    project_dir: "/opt/projects/my-project"
    allowed_tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep"]
    model: "sonnet"
    system_prompt: "You are helping with my-project development."

Running

# Set environment variables
export DISCORD_TOKEN="your-discord-bot-token"
export LOG_LEVEL="INFO"  # or DEBUG

# Run the bot
python -m claude_coordinator.bot

Using in Discord

1. Send message: @BotName help me debug this error
2. Check status: /status
3. Reset session: /reset
4. Switch model: /model opus

Monitoring

# Watch logs in real-time (JSON format)
tail -f ~/.claude-coordinator/logs/bot.log | jq .

# Check sessions
sqlite3 ~/.claude-coordinator/sessions.db "SELECT channel_id, project_name, message_count, last_active FROM sessions;"

🧪 Testing

# Run all tests
.venv/bin/python -m pytest

# Run specific test suite
.venv/bin/python -m pytest tests/test_bot.py -v

# Run with coverage
.venv/bin/python -m pytest --cov=claude_coordinator

Test Results: 156/157 passing (99.4%)

📊 Development Status

Completed (13/18 tasks)

Week 1 - Foundation (6/6 ✅)

• ✅ CRIT-001: CLI pattern validation
• ✅ CRIT-002: LXC hosting setup (10.10.0.230)
• ✅ CRIT-003: Project skeleton with uv
• ✅ CRIT-004: Claude subprocess runner
• ✅ CRIT-005: Session manager
• ✅ CRIT-006: Config system

Week 2 - Discord Integration MVP (4/4 ✅)

• ✅ HIGH-001: Discord bot with routing
• ✅ HIGH-002: Response formatter
• ✅ HIGH-003: Slash commands
• ✅ HIGH-004: Concurrent message handling

Week 3 - Operational Maturity (3/5 ✅)

• ✅ MED-001: Enhanced typing indicator
• ✅ MED-002: Structured logging
• ⏳ MED-003: Docker containerization (optional)
• ⏳ MED-004: Gitea integration tools
• ✅ MED-005: Comprehensive test suite

Week 4 - Extended Features (0/3)

• ⏳ LOW-001: Dynamic project setup channel
• ⏳ FEAT-001: Agent delegation
• ⏳ FEAT-002: MemoryGraph integration

🔧 Architecture

Message Flow

1. User sends @mention in Discord channel
2. Bot matches channel_id to project config
3. SessionManager retrieves session_id (or creates new)
4. ClaudeRunner executes: claude -p "message" --resume <id> --output-format json --permission-mode bypassPermissions
5. Response parsed from JSON output
6. SessionManager updates session metadata
7. ResponseFormatter chunks output for Discord
8. Bot sends formatted response(s)

Key Design Decisions

• Per-channel locking: Prevents session corruption from concurrent messages
• SQLite persistence: Simple, reliable, no external dependencies
• JSON logging: Machine-readable for monitoring/alerting
• Privacy-first errors: Internal details logged but not shown to users
• Subprocess pattern: Leverages existing Claude CLI, no API integration needed

📚 Documentation

• Bot Usage Guide - Complete usage instructions
• Slash Commands - Command reference
• Logging System - Log format and monitoring
• Deployment Checklist - Production deployment steps

🐛 Troubleshooting

Bot not responding?

• Check bot has message_content intent enabled in Discord Developer Portal
• Verify bot has permission to read and send messages in channel
• Check logs: tail -f ~/.claude-coordinator/logs/bot.log | jq .

Session not resuming?

• Check database: sqlite3 ~/.claude-coordinator/sessions.db "SELECT * FROM sessions;"
• Look for error IDs in logs and Discord messages

Claude CLI errors?

• Must run as discord-bot user (not root) for bypassPermissions
• Verify Claude CLI authenticated: claude -p "test" --output-format json

📝 License

TBD

🔗 Links

• Repository: https://git.manticorum.com/cal/ai-assistant-discord-bot
• Container: discord-bot@10.10.0.230 (LXC 301)
• Commits: 6b56463 → 4c00cd9 → e6983b5