Add custom commands with plugin loader

Author: dwash96

cecli/args.py

@@ -975,6 +975,12 @@ def get_parser(default_config_files, git_root):
             " specified, a default command for your OS may be used."
         ),
     )
+    group.add_argument(
+        "--command-paths",
+        help="JSON array of paths to custom commands files",
+        action="append",
+        default=None,
+    )
     group.add_argument(
         "--command-prefix",
         default=None,

cecli/coders/base_coder.py

@@ -429,7 +429,7 @@ def __init__(
 
         self.show_diffs = show_diffs
 
-        self.commands = commands or Commands(self.io, self)
+        self.commands = commands or Commands(self.io, self, args=args)
         self.commands.coder = self
 
         self.data_cache = {

cecli/commands/core.py

@@ -1,9 +1,11 @@
 import asyncio
+import json
 import re
 import sys
 from pathlib import Path
 
 from cecli.commands.utils.registry import CommandRegistry
+from cecli.helpers import plugin_manager
 from cecli.helpers.file_searcher import handle_core_files
 from cecli.repo import ANY_GIT_ERROR
 
@@ -77,9 +79,71 @@ def __init__(
         self.help = None
         self.editor = editor
         self.original_read_only_fnames = set(original_read_only_fnames or [])
+
+        try:
+            self.custom_commands = json.loads(getattr(self.args, "command_paths", "[]"))
+        except (json.JSONDecodeError, TypeError) as e:
+            self.io.tool_warning(f"Failed to parse command paths JSON: {e}")
+            self.custom_commands = []
+
+        # Load custom commands from plugin paths
+        self._load_custom_commands(self.custom_commands)
+
         self.cmd_running_event = asyncio.Event()
         self.cmd_running_event.set()
 
+    def _load_custom_commands(self, custom_commands):
+        """
+        Load custom commands from plugin paths.
+
+        Args:
+            custom_commands: List of file or directory paths to load custom commands from.
+                             If None or empty, no custom commands are loaded.
+        """
+        if not custom_commands:
+            return
+
+        for path_str in custom_commands:
+            path = Path(path_str)
+            try:
+                if path.is_dir():
+                    # Find all Python files in the directory
+                    for py_file in path.glob("*.py"):
+                        self._load_command_from_file(py_file)
+                else:
+                    # If it's a file, try to load it directly
+                    if path.exists() and path.suffix == ".py":
+                        self._load_command_from_file(path)
+            except Exception as e:
+                # Log error but continue with other paths
+                if self.io:
+                    self.io.tool_error(f"Error loading custom commands from {path}: {e}")
+
+    def _load_command_from_file(self, file_path):
+        """
+        Load a command class from a Python file.
+
+        Args:
+            file_path: Path to the Python file to load.
+        """
+        try:
+            # Load the module using plugin_manager
+            module = plugin_manager.load_module(str(file_path))
+
+            # Look for a class named exactly "CustomCommand" in the module
+            if hasattr(module, "CustomCommand"):
+                command_class = getattr(module, "CustomCommand")
+                if isinstance(command_class, type):
+                    # Register the command class
+                    CommandRegistry.register(command_class)
+                    if self.io and self.verbose:
+                        self.io.tool_output(f"Registered custom command: {command_class.NORM_NAME}")
+
+        except Exception as e:
+            # Log error but continue with other files
+            if self.io:
+                self.io.tool_error(f"Error loading command from {file_path}: {e}")
+
     def is_command(self, inp):
         return inp[0] in "/!"
 

cecli/main.py

@@ -554,6 +554,8 @@ async def main_async(argv=None, input=None, output=None, force_git_root=None, re
         args.tui_config = convert_yaml_to_json_string(args.tui_config)
     if hasattr(args, "mcp_servers") and args.mcp_servers is not None:
         args.mcp_servers = convert_yaml_to_json_string(args.mcp_servers)
+    if hasattr(args, "command_paths") and args.command_paths is not None:
+        args.command_paths = convert_yaml_to_json_string(args.command_paths)
     if args.debug:
         global log_file
         os.makedirs(".cecli/logs/", exist_ok=True)

cecli/website/docs/config/custom-commands.md

@@ -0,0 +1,187 @@
+# Custom Commands
+
+Cecli allows you to create and use custom commands to extend its functionality. Custom commands are Python classes that extend the `BaseCommand` class and can be loaded from specified directories or files.
+
+## How Custom Commands Work
+
+### Command Registry System
+
+Cecli uses a centralized command registry that manages all available commands:
+
+- **Built-in Commands**: Standard commands like `/add`, `/model`, `/help`, etc.
+- **Custom Commands**: User-defined commands loaded from specified paths
+- **Command Discovery**: Automatic loading of commands from configured directories
+
+### Configuration
+
+Custom commands can be configured using the `command-paths` configuration option in your YAML configuration file:
+
+```yaml
+command-paths: [".cecli/commands/", "~/my-commands/", "./special_command.py"]
+```
+
+The `command-paths` configuration option allows you to specify directories or files containing custom commands to load.
+
+The `command-paths` can include:
+- **Directories**: All `.py` files in the directory will be scanned for `CustomCommand` classes
+- **Individual Python files**: Specific command files can be loaded directly
+
+When cecli starts, it:
+1. **Parses configuration**: Reads `command-paths` from config files
+2. **Scans directories**: Looks for Python files in specified directories
+3. **Loads modules**: Imports each Python file as a module
+4. **Registers commands**: Finds classes named `CustomCommand` and registers them
+5. **Makes available**: Registered commands appear in `/help` and can be executed
+
+### Creating Custom Commands
+
+Custom commands are created by writing Python files that follow this structure:
+
+```python
+from typing import List
+from cecli.commands.utils.base_command import BaseCommand
+from cecli.commands.utils.helpers import format_command_result
+
+class CustomCommand(BaseCommand):
+    NORM_NAME = "custom-command"
+    DESCRIPTION = "Description of what the command does"
+
+    @classmethod
+    async def execute(cls, io, coder, args, **kwargs):
+        """
+        Execute the custom command.
+
+        Args:
+            io: InputOutput instance
+            coder: Coder instance (may be None for some commands)
+            args: Command arguments as string
+            **kwargs: Additional context
+
+        Returns:
+            Optional result (most commands return None)
+        """
+        # Command implementation here
+        result = f"Command executed with arguments: {args}"
+        return format_command_result(io, cls.NORM_NAME, result)
+
+    @classmethod
+    def get_completions(cls, io, coder, args) -> List[str]:
+        """
+        Get completion options for this command.
+
+        Args:
+            io: InputOutput instance
+            coder: Coder instance
+            args: Partial arguments for completion
+
+        Returns:
+            List of completion strings
+        """
+        # Return completion options or raise CommandCompletionException
+        # for dynamic completions
+        return []
+
+    @classmethod
+    def get_help(cls) -> str:
+        """
+        Get help text for this command.
+
+        Returns:
+            String containing help text for the command
+        """
+        help_text = super().get_help()
+        help_text += "\nAdditional information about this custom command."
+        return help_text
+```
+
+### Important Requirements
+
+1. **Class Name**: The command class **must** be named exactly `CustomCommand`
+2. **Inheritance**: Must inherit from `BaseCommand` (from `cecli.commands.utils.base_command`)
+3. **Class Properties**: Must define `NORM_NAME` and `DESCRIPTION` class attributes
+4. **Execute Method**: Must implement the `execute` class method
+
+### Example: Add List Command
+
+Here's a complete example of a custom command that adds a list of numbers:
+
+```python
+from typing import List
+from cecli.commands.utils.base_command import BaseCommand
+from cecli.commands.utils.helpers import format_command_result
+
+class CustomCommand(BaseCommand):
+    NORM_NAME = "add-list"
+    DESCRIPTION = "Add a list of numbers."
+
+    @classmethod
+    async def execute(cls, io, coder, args, **kwargs):
+        """Execute the context command with given parameters."""
+        num_list = map(int, filter(None, args.split(" ")))
+        return format_command_result(io, cls.NORM_NAME, sum(num_list))
+
+    @classmethod
+    def get_completions(cls, io, coder, args) -> List[str]:
+        """Get completion options for context command."""
+        # The original completions_context raises CommandCompletionException
+        # This is handled by the completion system
+        from cecli.io import CommandCompletionException
+        raise CommandCompletionException()
+
+    @classmethod
+    def get_help(cls) -> str:
+        """Get help text for the context command."""
+        help_text = super().get_help()
+        help_text += "Add list of integers"
+        return help_text
+```
+
+#### Complete Configuration Example
+
+Complete configuration example in YAML configuration file (`.cecli.conf.yml` or `~/.cecli.conf.yml`):
+
+```yaml
+# Model configuration
+model: gemini/gemini-3-pro-preview
+weak-model: gemini/gemini-3-flash-preview
+
+# Custom commands configuration
+command-paths: [".cecli/commands/"]
+
+# Other cecli options
+...
+```
+
+### Error Handling
+
+If there are errors loading custom commands:
+
+- **Invalid paths**: Warnings are logged but cecli continues to run
+- **Syntax errors**: The specific file fails to load but other commands still work
+- **Missing requirements**: Commands that can't be imported are skipped
+
+### Best Practices
+
+1. **Organize commands**: Group related commands in the same directory
+2. **Use descriptive names**: Make `NORM_NAME` clear, memorable, and unique
+3. **Provide good help**: Implement `get_help()` with clear usage instructions
+4. **Handle errors gracefully**: Use `format_command_result()` for consistent output
+5. **Test commands**: Verify commands work before adding to production config
+
+### Integration with Other Features
+
+Custom commands work seamlessly with other cecli features:
+
+- **Command completion**: Custom commands appear in tab completion
+- **Help system**: Included in `/help` output
+- **TUI interface**: Available in the graphical interface
+- **Agent Mode**: Can be used alongside Agent Mode tools
+
+### Benefits
+
+- **Extensibility**: Add project-specific functionality
+- **Automation**: Create commands for repetitive tasks
+- **Integration**: Connect cecli with other tools and systems
+- **Customization**: Tailor cecli to your specific workflow
+
+Custom commands provide a powerful way to extend cecli's capabilities, allowing you to create specialized functionality for your specific needs while maintaining the familiar command interface.