ai-assistant-discord-bot/docs/COMMANDS_USAGE.md

Slash Commands Usage Guide

The Claude Coordinator Discord bot now supports slash commands for managing Claude sessions and monitoring bot activity.

Available Commands

/reset [channel]

Clear the Claude session for a channel, starting fresh conversations.

Usage:

/reset                    # Reset current channel
/reset channel:#dev       # Reset specific channel

Features:

• Requires Manage Messages permission
• Shows confirmation dialog with session details before resetting
• Displays project name and message count
• Yes/No buttons for confirmation (60 second timeout)

Example Output:

⚠️ Reset Session Confirmation

Channel: #major-domo
Project: major-domo-bot
Messages: 42

Are you sure you want to clear this session? This will delete all conversation history.

[Yes, Reset] [Cancel]

After Confirmation:

✅ Session Reset

Channel: #major-domo
Project: major-domo-bot

Session history cleared. The next message will start a fresh conversation.

---

/status

Show all active Claude sessions across configured channels.

Usage:

/status    # View all active sessions

Features:

• Shows ephemeral message (only visible to you)
• Displays channel name, project, message count, and last activity
• Formatted as Discord embed for clarity
• Automatically calculates time since last activity

Example Output:

📊 Claude Coordinator Status

2 active session(s)

#major-domo
Project: major-domo-bot
Messages: 42
Last Active: 5m ago

#paper-dynasty
Project: paper-dynasty-frontend
Messages: 23
Last Active: 2h ago

Total messages: 65 | Database: ~/.claude-coordinator/sessions.db

No Sessions:

📊 Claude Coordinator Status

No active sessions.

Database: ~/.claude-coordinator/sessions.db

---

/model <model_name>

Switch the Claude model used for a channel's sessions.

Usage:

/model model_name:sonnet    # Use Claude Sonnet (default)
/model model_name:opus      # Use Claude Opus (most capable)
/model model_name:haiku     # Use Claude Haiku (fastest)

Features:

• Updates configuration file permanently
• Shows previous and new model
• Takes effect on next Claude request
• Does not affect existing session history

Model Options:

• Claude Sonnet (default) - claude-sonnet-4-5 - Balanced performance
• Claude Opus (most capable) - claude-opus-4-6 - Best for complex tasks
• Claude Haiku (fastest) - claude-3-5-haiku - Quick responses

Example Output:

✅ Model Updated

Channel: #major-domo
Previous: claude-sonnet-4-5
New: claude-opus-4-6

The new model will be used for the next Claude request.

---

Permission Requirements

/reset

• Required: Manage Messages permission
• Scope: Per-channel or server-wide

/status

• Required: None (public command)
• Shows only channels the bot has configured

/model

• Required: None (public command)
• Only affects the channel where used

---

Error Messages

Channel Not Configured

❌ Channel #example is not configured for Claude Coordinator.

Solution: Add the channel to your config.yaml file.

No Active Session

ℹ️ No active session found for #example.

Info: No session exists to reset. The next message will create a new session.

Missing Permissions

❌ You need Manage Messages permission to use this command.

Solution: Ask a server admin to grant you the required permission.

---

Technical Details

Command Registration

Commands are registered via Discord's application command system and synced on bot startup:

# In bot.py setup_hook()
await self.load_extension("claude_coordinator.commands")
synced = await self.tree.sync()
logger.info(f"Synced {len(synced)} application commands")

Database Operations

All commands interact with the SessionManager:

• /reset → session_manager.reset_session(channel_id)
• /status → session_manager.list_sessions() + get_stats()
• /model → Updates config.yaml via Config.save()

Response Types

• Ephemeral: /reset and /status responses only visible to command user
• Interactive: /reset uses Discord UI buttons for confirmation
• Persistent: /model changes are saved to configuration file

---

Testing

Run command tests:

pytest tests/test_commands.py -v

Test coverage:

• ✅ /reset success, no session, unconfigured channel, target channel, error handling
• ✅ Confirmation view buttons (confirm, cancel)
• ✅ /status with sessions, empty sessions, error handling
• ✅ /model all choices (sonnet/opus/haiku), unconfigured channel, error handling
• ✅ Permission checks and error handlers
• ✅ Cog initialization and setup

Total: 18 test cases, all passing