
# Slash Commands Guide

## Overview

Slash commands in the Kollabor system are implemented through an event-driven architecture that integrates with the input handling system. When users type commands starting with `/`, they are parsed, registered, and executed through a comprehensive command framework.

## Architecture

The slash command system is built around several core components defined in `kollabor/events/models.py` and implemented in `kollabor/commands/`:

### Core Data Models

The system uses several key data models defined in `kollabor/events/models.py`:

- **SlashCommand**: Represents a parsed command with name, arguments, and metadata
- **CommandDefinition**: Defines a command with handler, metadata, and configuration
- **CommandResult**: Represents the result of command execution
- **CommandMode**: Enum defining different command execution modes
- **CommandCategory**: Enum for organizing commands by category

### Core Components

1. **Command Parser** (`kollabor/commands/parser.py`)
   - Detects slash commands in user input
   - Parses command names and arguments using shell-like parsing
   - Handles quoted arguments and parameter extraction
   - Validates command structure

2. **Command Registry** (`kollabor/commands/registry.py`)
   - Manages command registration and discovery
   - Handles command aliases and conflict detection
   - Organizes commands by plugin and category
   - Provides search and lookup functionality

3. **Command Executor** (`kollabor/commands/executor.py`)
   - Executes registered commands with proper error handling
   - Integrates with event bus for lifecycle events
   - Handles different command modes (INSTANT, STATUS_TAKEOVER, etc.)
   - Manages UI configuration for modal commands

4. **System Commands** (`kollabor/commands/system_commands.py`)
   - Provides built-in system commands
   - Registers core functionality like help, config, status
   - Implements command handlers for essential system operations

5. **Menu Renderer** (`kollabor/commands/menu_renderer.py`)
   - Renders interactive command menu overlay
   - Handles command filtering and selection
   - Provides visual feedback for command navigation

## Command Structure

### Basic Syntax

```
/command_name [argument1] [argument2] [--flag=value]
```

### Parsing Features

The parser supports:

- **Quoted arguments**: `/save "my file.txt"`
- **Flag arguments**: `/config --theme=dark --verbose`
- **Short flags**: `/run -f script.py`
- **Boolean flags**: `/debug --enable`

### Command Detection

Commands are detected in the input handler when:
1. User input starts with `/`
2. Input is parsed by `SlashCommandParser`
3. Command is looked up in the registry
4. Command is executed through the executor

## Command Registration

### Command Definition Structure

Commands are registered using `CommandDefinition`:

```python
from kollabor.events.models import CommandDefinition, CommandMode, CommandCategory

command_def = CommandDefinition(
    name="help",
    description="Show available commands",
    handler=self.handle_help,
    plugin_name="system",
    category=CommandCategory.SYSTEM,
    mode=CommandMode.INSTANT,
    aliases=["h", "?"],
    icon="❓"
)
```

### Subcommands

Commands can define subcommands for better discoverability and tab-completion style input. Subcommands appear in the command menu when the user filters to a single command.

```python
from kollabor.events.models import CommandDefinition, SubcommandInfo

command_def = CommandDefinition(
    name="profile",
    description="Manage LLM API profiles",
    handler=self.handle_profile,
    plugin_name="system",
    category=CommandCategory.SYSTEM,
    subcommands=[
        SubcommandInfo("list", "", "Show profile selection modal"),
        SubcommandInfo("set", "<name>", "Switch to specified profile"),
        SubcommandInfo("create", "", "Open create profile form"),
    ]
)
```

#### SubcommandInfo Structure

- **name**: The subcommand name (e.g., "list", "set", "create")
- **args**: Argument placeholder (e.g., "<name>", "[optional]", "" for none)
- **description**: Brief description shown in the menu

#### Subcommand Behavior

Subcommands have smart execution behavior based on whether they require arguments:

- **No-arg subcommands** (empty args string): Execute immediately when selected
  - Example: `/profile create` opens the create form directly

- **Arg subcommands** (non-empty args string): Insert text for user to complete
  - Example: Selecting `set <name>` inserts `/profile set ` and waits for user input

#### Menu Display

Subcommands only appear in the command menu when filtered to a single command:

```
# Typing "/" shows main menu (no subcommands)
/
 ⚙  System
 ◆  /config   Open system configuration panel
    /help     Show available commands
    /profile  Manage LLM API profiles
    /status   Show system status

# Typing "/prof" filters to single command (shows subcommands)
/prof
 ⚙  System
 ◆  /profile  Manage LLM API profiles
      list                 Show profile selection modal
      set <name>           Switch to specified profile
      create               Open create profile form
```

### Registration Process

1. **System Commands**: Registered in `SystemCommandsPlugin.register_commands()`
2. **Plugin Commands**: Registered through plugin initialization
3. **Validation**: Registry validates command definitions
4. **Conflict Detection**: Prevents duplicate command names
5. **Alias Resolution**: Maps aliases to command names

### Command Modes

Different modes affect how commands are displayed and handled:

- **INSTANT**: Commands that execute immediately and show results
- **STATUS_TAKEOVER**: Commands that take over the status area
- **MODAL**: Commands that open modal overlays
- **MENU_POPUP**: Commands that show interactive menus

## Available Commands

### System Commands

Built-in commands provided by `SystemCommandsPlugin` in `kollabor/commands/system_commands.py`:

- `/help` (aliases: `/h`, `/?`) - Show available commands and usage
  - Mode: INSTANT
  - Category: SYSTEM

- `/version` (aliases: `/v`, `/ver`) - Show application version information
  - Mode: INSTANT
  - Category: SYSTEM

- `/config` (aliases: `/settings`, `/preferences`) - Open system configuration panel
  - Mode: STATUS_TAKEOVER
  - Category: SYSTEM

- `/status` (aliases: `/info`, `/diagnostics`) - Show system status and diagnostics
  - Mode: STATUS_TAKEOVER
  - Category: SYSTEM

- `/permissions` (aliases: `/perms`, `/security`) - Manage tool execution permissions
  - Mode: INLINE_INPUT
  - Category: SYSTEM
  - Subcommands: `show`, `default`, `strict`, `trust`, `stats`, `clear`

- `/cd` (aliases: `/chdir`, `/dir`) - Change working directory
  - Mode: STATUS_TAKEOVER
  - Category: SYSTEM
  - Subcommands: `<path>`, `..`, `-`

- `/widgets` (aliases: `/showcase`, `/widget-showcase`, `/storybook`) - Interactive widget gallery
  - Mode: STATUS_TAKEOVER
  - Category: UI

### LLM Commands

- `/profile` (aliases: `/prof`, `/llm`) - Manage LLM API profiles
  - Mode: STATUS_TAKEOVER
  - Category: SYSTEM
  - Subcommands: `list`, `set <name>`, `create`

- `/model` (aliases: `/mod`, `/m`) - Quick model selector
  - Mode: STATUS_TAKEOVER
  - Category: SYSTEM
  - Subcommands: `list`, `set <name>`

### Agent Commands

- `/agent` (aliases: `/ag`) - Manage agents and their configurations
  - Mode: STATUS_TAKEOVER
  - Category: AGENT
  - Subcommands: `list`, `set <name>`, `create`, `clear`

- `/skill` (aliases: `/sk`) - Load or unload agent skills
  - Mode: STATUS_TAKEOVER
  - Category: AGENT
  - Subcommands: `list`, `load <name>`, `unload <name>`, `create`

### MCP Commands

Registered by `MCPCommandHandler` in `kollabor/commands/mcp_command.py`:

- `/mcp` (aliases: `/mcps`, `/servers`) - Manage MCP (Model Context Protocol) servers
  - Mode: INSTANT
  - Category: SYSTEM
  - Subcommands: `setup`, `list`, `test <server>`, `enable <server>`, `disable <server>`, `show`, `tools [server]`

### Conversation Commands

Registered by `SaveConversationPlugin` and `ResumeConversationPlugin`:

- `/save` (aliases: `/export`, `/transcript`) - Save conversation to file or clipboard
  - Mode: INSTANT
  - Category: CONVERSATION
  - Subcommands: `transcript`, `markdown`, `jsonl`, `clipboard`, `both`, `local`
  - Examples:
    - `/save` - Save to file in transcript format
    - `/save clipboard` - Copy to clipboard
    - `/save local` - Save to current working directory
    - `/save markdown local` - Save markdown to current directory

- `/resume` (aliases: `/restore`, `/continue`) - Resume a previous conversation session
  - Mode: STATUS_TAKEOVER
  - Category: CONVERSATION

- `/sessions` (aliases: `/history`, `/conversations`) - Search and browse conversation sessions
  - Mode: STATUS_TAKEOVER
  - Category: CONVERSATION

- `/branch` - Branch conversation from a specific message
  - Mode: STATUS_TAKEOVER
  - Category: CONVERSATION

### Terminal Commands

Registered by `TmuxPlugin` in `plugins/tmux_plugin.py`:

- `/terminal` (aliases: `/tmux`, `/term`, `/t`) - Manage tmux terminal sessions
  - Mode: INSTANT
  - Category: CUSTOM
  - Subcommands: `new <name> <cmd>`, `view [name]`, `list`, `kill <name>`, `attach <name>`

### Agent Orchestrator Commands

Registered by `AgentOrchestratorPlugin` in `plugins/agent_orchestrator/plugin.py`:

- `/sub` (aliases: `/subagent`, `/sa`) - Manage parallel agent sessions
  - Mode: INSTANT
  - Category: CUSTOM
  - Subcommands: `list`, `status [name]`, `create <name> <task>`, `capture <name|all> [lines]`, `stop <name|all>`, `message <name> <msg>`
  - Examples:
    - `/sub list` - List all active agents
    - `/sub status` - Show status of all agents
    - `/sub capture all` - Capture output from all agents
    - `/sub stop myagent` - Stop specific agent

### Fullscreen Plugin Commands

Registered dynamically by fullscreen plugins in `plugins/fullscreen/`:

- `/matrix` - Enter the Matrix with falling code rain effect
  - Mode: FULLSCREEN
  - Category: EFFECTS

- `/space` (aliases: `/shooter`, `/galaga`, `/arcade`) - 80s arcade space shooter demo
  - Mode: FULLSCREEN
  - Category: EFFECTS

- `/status-setup` (aliases: `/status-config`, `/status-edit`) - Configure status area layout
  - Mode: FULLSCREEN
  - Category: SYSTEM

- `/example` (aliases: `/demo`, `/showcase`) - Comprehensive framework showcase
  - Mode: FULLSCREEN
  - Category: DEMO

### Command Categories

Commands are organized into categories:

- **SYSTEM**: Core system management (`/help`, `/config`, `/status`, `/permissions`, `/version`, `/cd`, `/profile`, `/model`, `/mcp`)
- **AGENT**: Agent-related operations (`/agent`, `/skill`)
- **CONVERSATION**: Conversation management (`/save`, `/resume`, `/sessions`, `/branch`)
- **CUSTOM**: Plugin-specific commands (`/terminal`, `/sub`)
- **UI**: User interface commands (`/widgets`)
- **EFFECTS**: Visual effect commands (`/matrix`, `/space`)
- **DEMO**: Demonstration commands (`/example`)

## Command Implementation

### Handler Function Signature

Command handlers must accept a `SlashCommand` object:

```python
async def handle_help(self, command: SlashCommand) -> CommandResult:
    """Handle help command."""
    try:
        if command.args:
            # Show help for specific command
            return await self._show_command_help(command.args[0])
        else:
            # Show all commands
            return await self._show_all_commands()
    except Exception as e:
        return CommandResult(
            success=False,
            message=f"Error displaying help: {str(e)}",
            display_type="error"
        )
```

### Command Result Structure

Commands return `CommandResult` objects:

```python
return CommandResult(
    success=True,
    message="Command completed successfully",
    display_type="info",  # info, success, warning, error
    data={"key": "value"},  # Optional additional data
    ui_config=None  # Optional UI configuration for modals
)
```

### UI Configuration

Commands can specify UI configurations for different display modes:

```python
from kollabor.events.models import UIConfig

ui_config = UIConfig(
    type="modal",
    title="Configuration",
    width=80,
    height=20,
    modal_config={
        "sections": [...],
        "footer": "Navigation instructions"
    }
)
```

## Integration with Input System

### Command Detection Flow

1. **Input Detection**: `InputHandler` detects `/` at start of input
2. **Command Mode Entry**: System enters `CommandMode.MENU_POPUP`
3. **Menu Display**: Interactive menu shows available commands
4. **Command Filtering**: Menu filters as user types
5. **Command Selection**: User selects command with arrow keys
6. **Command Execution**: Selected command is parsed and executed

### Event Integration

The command system integrates with the event bus:

- **SLASH_COMMAND_DETECTED**: Emitted when command is detected
- **SLASH_COMMAND_EXECUTE**: Emitted when command starts execution
- **SLASH_COMMAND_COMPLETE**: Emitted when command finishes
- **SLASH_COMMAND_ERROR**: Emitted when command fails
- **COMMAND_MENU_SHOW/HIDE**: Emitted for menu lifecycle events

### Hook System

Commands can register hooks for:

- **COMMAND_MENU_RENDER**: Provide menu content for display
- **MODAL_TRIGGER**: Handle modal display requests
- **STATUS_MODAL_TRIGGER**: Handle status modal requests
- **COMMAND_OUTPUT_DISPLAY**: Display command results

## Error Handling

### Validation Layers

1. **Input Validation**: Parser validates command structure
2. **Registry Validation**: Registry validates command definitions
3. **Execution Validation**: Executor validates command state
4. **Handler Validation**: Individual handlers validate arguments

### Error Types

Common error scenarios:

- **Command Not Found**: Unknown command name
- **Invalid Arguments**: Missing or malformed arguments
- **Permission Denied**: Insufficient permissions
- **Handler Error**: Exception in command handler
- **System Error**: Internal system failures

### Error Response Format

```python
CommandResult(
    success=False,
    message="Error: Command 'unknown' not found",
    display_type="error",
    error_code="COMMAND_NOT_FOUND",
    data={"suggestions": ["help", "status"]}
)
```

## Testing Commands

### Unit Tests

Located in `tests/unit/test_slash_commands.py`:

- Test command parsing and validation
- Test registry operations
- Test executor functionality
- Test error handling scenarios

### Integration Tests

Located in `tests/integration/test_slash_commands_integration.py`:

- Test end-to-end command flow
- Test system commands registration
- Test menu functionality
- Test event integration

## Extending the System

### Adding New Commands

1. **Create Command Handler**: Implement handler function
2. **Create Command Definition**: Define command metadata
3. **Register Command**: Add to registry during initialization
4. **Add Tests**: Write unit and integration tests

### Plugin Commands

Plugins can register commands:

```python
class MyPlugin:
    async def initialize(self, event_bus, config, **kwargs):
        command_registry = kwargs.get('command_registry')
        if command_registry:
            command_def = CommandDefinition(
                name="mycommand",
                description="My custom command",
                handler=self.handle_my_command,
                plugin_name=self.name,
                category=CommandCategory.CUSTOM
            )
            command_registry.register_command(command_def)
```

### Custom Command Categories

Extend `CommandCategory` enum in `kollabor/events/models.py`:

```python
class CommandCategory(Enum):
    SYSTEM = "system"
    CONVERSATION = "conversation"
    # Add new categories
    MY_CATEGORY = "my_category"
```

## Performance Considerations

### Registry Optimization

- Commands are indexed by name for fast lookup
- Aliases are mapped to canonical names
- Categories are cached for efficient grouping

### Memory Management

- Command definitions are stored once in registry
- Parsed commands are lightweight objects
- Event emissions are minimized for performance

### Async Operations

- All command handlers should be async
- Long-running operations should use await
- Event emissions are non-blocking

## Security

### Input Sanitization

- Command names are validated against allowed characters
- Arguments are processed safely using shlex.split()
- Control characters are filtered from input

### Permission System

Commands can specify permission requirements:

```python
command_def = CommandDefinition(
    name="admin",
    description="Admin-only command",
    handler=self.handle_admin,
    permission="admin"  # Required permission level
)
```

### Sandboxing

Consider sandboxing for:

- File operations in plugin commands
- Network access in untrusted commands
- System command execution

## Debugging

### Logging

Enable debug logging for command system:

```python
import logging
logging.getLogger("kollabor.commands").setLevel(logging.DEBUG)
```

### Registry Statistics

Get registry information for debugging:

```python
stats = command_registry.get_registry_stats()
print(f"Commands: {stats['total_commands']}")
print(f"Plugins: {stats['plugins']}")
```

### Command Tracing

Trace command execution through events:

```python
# Hook into command events for debugging
await event_bus.register_hook(Hook(
    name="debug_commands",
    event_type=EventType.SLASH_COMMAND_EXECUTE,
    callback=self.trace_command_execution
))
```

## Future Enhancements

### Planned Features

1. **Command Autocomplete**: Tab completion for commands and arguments
2. **Command History**: Navigate through previous commands
3. **Command Pipelines**: Chain commands together
4. **Custom Shortcuts**: User-defined command aliases
5. **Interactive Help**: Context-sensitive help system

### Extension Points

1. **Custom Parsers**: Plugin-specific argument parsers
2. **Result Formatters**: Custom output formatting
3. **Validation Rules**: Custom argument validation
4. **Middleware**: Pre/post processing hooks

## Conclusion

The slash command system provides a robust, extensible framework for user interaction in Kollabor. By following the established patterns and interfaces, developers can create powerful commands that integrate seamlessly with the existing architecture.

For implementation details, refer to the source code in `kollabor/commands/` and the test files in `tests/`.

---

## Related Documentation

- **[Resume Command Specification](../features/RESUME_COMMAND_SPEC.md)** - Complete specification for the `/resume` command
- **[Config Command Enhancement Spec](../CONFIG_COMMAND_ENHANCEMENT_SPEC.md)** - Detailed configuration system documentation
- **[Modal System Implementation Guide](../modal-system-implementation-guide.md)** - Modal UI framework documentation
