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:

```python
# 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:
```bash
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