224 lines
7.3 KiB
Markdown
224 lines
7.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
cd /opt/projects/claude-coordinator
|
|
source .venv/bin/activate # Already created with uv
|
|
```
|
|
|
|
### Configuration
|
|
|
|
Create `config.yaml`:
|
|
```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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](docs/BOT_USAGE.md) - Complete usage instructions
|
|
- [Slash Commands](docs/COMMANDS_USAGE.md) - Command reference
|
|
- [Logging System](docs/LOGGING.md) - Log format and monitoring
|
|
- [Deployment Checklist](DEPLOYMENT_CHECKLIST.md) - 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
|