Update README with production-ready status (13/18 tasks)

2026-02-13 19:26:43 +00:00 · 2026-02-13 19:26:43 +00:00 · 3ccfbe5f99
commit 3ccfbe5f99
parent e6983b56b9
1 changed files with 194 additions and 43 deletions
--- a/README.md
+++ b/README.md
@ -1,72 +1,223 @@
 # Claude Discord Coordinator

-A Discord bot that provides multi-user access to Claude CLI sessions with persistence, configuration management, and formatted responses.
+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.

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

- **Multi-user sessions**: Each Discord user gets their own persistent Claude CLI session
- **Session persistence**: Conversation history and working directories saved in SQLite
- **YAML configuration**: Flexible bot configuration with environment variable support
- **Response formatting**: Automatic chunking and code block formatting for Discord
- **Subprocess management**: Robust Claude CLI process handling with timeout control
+## 🎯 What It Does

-## Project Structure
+- 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/
-├── pyproject.toml          # uv project configuration
-├── README.md              # This file
-├── .gitignore            # Python/uv ignore patterns
-└── claude_coordinator/   # Main package
-    ├── __init__.py       # Package initialization
-    ├── bot.py            # Discord bot entry point
-    ├── config.py         # YAML configuration management
-    ├── session_manager.py # SQLite session persistence
-    ├── claude_runner.py  # Claude CLI subprocess wrapper
-    └── response_formatter.py # Discord message formatting
+├── 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
 ```

-## Requirements
+## 🚀 Quick Start

+### Prerequisites
 - Python 3.12+
- uv 0.10.2+
- Claude CLI (authenticated)
+- Claude CLI authenticated (as discord-bot user)
+- Discord bot token

-## Dependencies
-
- discord.py 2.6.4+ - Discord bot framework
- aiosqlite 0.22.1+ - Async SQLite interface
- pyyaml 6.0.3+ - YAML configuration parsing
-
-## Installation
+### Installation

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

-## Configuration
+### Configuration

-Configuration will be loaded from a YAML file (to be implemented in CRIT-004).
+Create `config.yaml`:
+```yaml
+discord:
+  token: "your-discord-bot-token"  # Or use DISCORD_TOKEN env var

-## Usage
+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
-# Run the bot (entry point to be completed)
-uv run python -m claude_coordinator.bot
+# Set environment variables
+export DISCORD_TOKEN="your-discord-bot-token"
+export LOG_LEVEL="INFO"  # or DEBUG
+
+# Run the bot
+python -m claude_coordinator.bot
 ```

-## Development Status
+### Using in Discord

-This project is under active development. Current implementation status:
+1. **Send message**: `@BotName help me debug this error`
+2. **Check status**: `/status`
+3. **Reset session**: `/reset`
+4. **Switch model**: `/model opus`

- [x] CRIT-003: Project skeleton with uv
- [ ] CRIT-004: Configuration system
- [ ] CRIT-005: Session management
- [ ] CRIT-006: Claude CLI integration
- [ ] CRIT-007: Discord bot commands
- [ ] CRIT-008: Testing and deployment
+### Monitoring

-## License
+```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