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.

---

/add-project <project_name> <git_url> [channel] [model]

Dynamically add a new project configuration without restarting the bot.

Usage:

/add-project project_name:my-project git_url:https://git.manticorum.com/cal/my-project.git
/add-project project_name:paper-dynasty git_url:https://git.example.com/pd.git channel:#dev model:opus

Parameters:

• project_name (required) - Short name for the project (lowercase, alphanumeric, hyphens/underscores only)
• git_url (required) - Git repository URL to clone
• channel (optional) - Channel to map (defaults to current channel)
• model (optional) - Claude model to use: sonnet (default), opus, or haiku

Features:

• Requires Administrator permission
• Clones repository to /opt/projects/{project_name}
• Uses shallow clone (--depth 1) for faster cloning
• Validates project name format
• Checks for duplicate channel configuration
• Validates cloned repository structure
• Updates configuration file automatically
• No bot restart required - changes take effect immediately
• Rolls back changes on failure

Workflow:

1. Validates inputs (project name format, channel not already configured)
2. Clones git repository with 2-minute timeout
3. Validates cloned directory is a valid git repository
4. Adds project to configuration
5. Saves configuration atomically to disk
6. Reloads configuration (live update!)

Example Output:

✅ Project Added Successfully

Project: paper-dynasty
Channel: #development
Model: opus
Directory: /opt/projects/paper-dynasty
Repository: https://git.manticorum.com/cal/paper-dynasty.git

You can now @mention the bot in this channel!

Error Handling:

Invalid Project Name:

❌ Project name must be lowercase alphanumeric with hyphens/underscores only

Channel Already Configured:

❌ Channel #development is already configured!

Directory Already Exists:

❌ Directory already exists: /opt/projects/paper-dynasty

Git Clone Failure:

❌ Git clone failed:
fatal: repository 'https://git.example.com/invalid.git' not found

Git Clone Timeout:

❌ Git clone timed out (>2 minutes)

Not a Git Repository:

❌ Cloned directory doesn't appear to be a git repository

Configuration Error (with Rollback):

❌ Failed to update configuration: Disk full

Rolled back changes.

Important Notes:

• Repository must be publicly accessible or SSH keys must be configured on the bot server
• Project name becomes the directory name in /opt/projects/
• Default allowed tools: Bash, Read, Write, Edit, Glob, Grep
• Configuration is saved to ~/.claude-coordinator/config.yaml
• Use --depth 1 shallow clone to save disk space and time
• Rollback automatically removes cloned directory if configuration fails

---

Permission Requirements

/reset

• Required: Manage Messages permission

/add-project

• Required: Administrator permission
• Scope: Server-wide administration
• 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: 30 test cases, all passing (18 original + 12 for /add-project)