# 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