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:

```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:** 30 test cases, all passing (18 original + 12 for /add-project)