Skip to content

Architecture 1 CLI

Jump to bottom
Danny Volz edited this page Jul 8, 2025 · 3 revisions

CLI Module Architecture

Code References

  • Primary implementation: coda/cli/main.py
  • Interactive mode: coda/cli/interactive_cli.py, coda/cli/interactive.py
  • Command registry: coda/cli/command_registry.py
  • Chat session: coda/cli/chat_session.py
  • Provider management: coda/cli/provider_manager.py
  • Tests: tests/cli/
  • Shared components: coda/cli/shared/

Overview

The CLI module is responsible for the command-line interface of Coda Code Assistant. It provides both a basic mode for simple interactions and a rich interactive mode with auto-completion, themes, and advanced features. The main entry point is the main() function in coda/cli/main.py:25-89.

Module Structure

coda/cli/
├── __init__.py              # Module initialization
├── main.py                  # Entry point and basic mode (verified)
├── interactive.py           # Interactive mode runner (verified)
├── interactive_cli.py       # Interactive CLI implementation (verified)
├── chat_session.py          # Chat session management (verified)
├── command_registry.py      # Command definitions (verified)
├── provider_manager.py      # Provider initialization (verified)
├── error_handler.py         # Error handling (verified)
├── basic_commands.py        # Basic mode commands (verified)
├── agent_chat.py            # Agent integration (verified)
├── model_selector.py        # Model selection UI (verified)
├── theme_selector.py        # Theme selection UI (verified)
├── tool_chat.py            # Tool chat integration (verified)
└── shared/                  # Shared components (verified)
    ├── commands.py          # Command handler base
    ├── help.py             # Help formatting
    └── modes.py            # Developer modes

Key Components

Component 1: Entry Point

Location: coda/cli/main.py:25-89

Purpose: Main entry point that determines CLI mode and initializes the application

Key Functions:

  • main() (lines 25-89): Click command that handles CLI arguments and mode selection
  • run_basic_mode() (lines 91-138): Executes basic CLI mode without prompt-toolkit
  • show_welcome_banner() (lines 140-153): Displays welcome message with version info

Component 2: Command Registry

Location: coda/cli/command_registry.py:64-346

Purpose: Centralized registry of all CLI commands with metadata and autocomplete support

Key Classes:

  • CommandType (lines 8-14): Enum defining command categories
  • CommandDefinition (lines 17-41): Dataclass for command metadata
  • CommandRegistry (lines 64-346): Central registry managing all commands

Component 3: Interactive CLI

Location: coda/cli/interactive_cli.py:144-656

Purpose: Rich interactive interface with prompt-toolkit integration

Key Classes:

  • SlashCommand (lines 23-31): Command representation
  • SlashCommandCompleter (lines 33-110): Auto-completion provider
  • InteractiveCLI (lines 144-656): Main interactive CLI implementation

Component 4: Chat Session

Location: coda/cli/chat_session.py:22-219

Purpose: Manages conversation flow for both basic and interactive modes

Key Methods:

  • stream_response() (lines 56-114): Handles streaming AI responses
  • run_one_shot() (lines 121-153): Single prompt execution
  • run_interactive() (lines 154-219): Interactive chat loop

Implementation Details

Design Patterns Used

Registry Pattern

Implementation: coda/cli/command_registry.py:64-346

class CommandRegistry:  # line 64
    """Central registry for all CLI commands."""
    
    def __init__(self):  # line 67
        self.commands: Dict[str, CommandDefinition] = {}  # line 68
        self._initialize_commands()  # line 69

Command Pattern

Implementation: coda/cli/shared/commands.py:23-367

The command handler base class implements the command pattern:

class CommandHandler(ABC):  # line 23
    """Abstract base class for command handling."""
    
    @abstractmethod
    async def handle_command(self, command: str, args: str) -> CommandResult:  # line 36
        """Handle a command with arguments."""
        pass

Template Method Pattern

Implementation: coda/cli/shared/commands.py:44-367

Base class provides shared implementations that subclasses can use:

async def handle_mode_command(self, mode_name: str) -> CommandResult:  # line 44
    """Shared implementation for mode switching."""
    # Implementation details...

Data Flow

sequenceDiagram
    participant User
    participant Main as main.py
    participant CLI as InteractiveCLI
    participant Registry as CommandRegistry
    participant Session as ChatSession
    participant Provider
    
    User->>Main: coda chat
    Main->>Main: Load configuration
    Main->>CLI: Initialize interactive mode
    CLI->>Registry: Load command definitions
    
    loop Interactive Session
        CLI->>User: Display prompt
        User->>CLI: Input message/command
        alt Slash Command
            CLI->>Registry: Lookup command
            CLI->>CLI: Execute command handler
        else Chat Message
            CLI->>Session: Process message
            Session->>Provider: Send to AI
            Provider->>Session: Stream response
            Session->>CLI: Display response
        end
    end
Loading

Class Hierarchy

classDiagram
    CommandHandler <|-- InteractiveCLI
    CommandHandler <|-- BasicCommands
    
    class CommandHandler {
        <<abstract>>
        +handle_command(command, args)
        +handle_mode_command(mode)
        +handle_model_command(args)
    }
    
    class InteractiveCLI {
        +get_input()
        +process_slash_command()
        +run()
    }
    
    class BasicCommands {
        +handle_command()
        +get_user_input()
    }
    
    note for CommandHandler "Defined in shared/commands.py:23-367"
    note for InteractiveCLI "Defined in interactive_cli.py:144-656"
Loading

API Reference

Public Functions

main(basic: bool, provider: str, model: str, chat: tuple, one_shot: bool) -> None

Location: coda/cli/main.py:25

Purpose: Main CLI entry point

Parameters:

  • basic (bool): Use basic mode without prompt-toolkit
  • provider (str): Provider name to use
  • model (str): Model name to use
  • chat (tuple): Initial chat messages
  • one_shot (bool): Exit after first response

Public Classes

InteractiveCLI

Location: coda/cli/interactive_cli.py:144-656

Purpose: Rich interactive CLI with auto-completion and themes

Key Methods:

  • __init__(self, provider, config, theme): Constructor (line 150)
  • get_input(self) -> Optional[str]: Get user input with features (line 361)
  • process_slash_command(self, command: str) -> bool: Handle commands (line 400)
  • run(self): Main interactive loop (line 583)

ChatSession

Location: coda/cli/chat_session.py:22-219

Purpose: Manages chat conversations with AI providers

Key Methods:

  • __init__(self, provider, config, theme, mode): Constructor (line 23)
  • stream_response(self, prompt: str): Stream AI response (line 56)
  • run_interactive(self, handler): Interactive chat loop (line 154)

Configuration

Config File: ~/.config/coda/config.toml Config Class: coda/configuration.py:CodaConfig

Configuration Options Used

Option Type Default Description Used In
default_provider str "ollama" Default AI provider main.py:56
theme str "monokai" UI color theme main.py:72
autosave.enabled bool True Auto-save sessions interactive_cli.py:234
debug bool False Debug mode error_handler.py:45

Dependencies

Internal Dependencies

  • coda.configuration: Configuration management (main.py:12)
  • coda.providers: AI provider implementations (provider_manager.py:5)
  • coda.session: Session persistence (interactive_cli.py:17)
  • coda.themes: UI theming system (main.py:16)
  • coda.agents: Agent system for tools (agent_chat.py:6)

External Dependencies

  • click>=8.1.7: Command-line interface creation
  • prompt_toolkit>=3.0.36: Rich terminal UI
  • rich>=13.7.0: Terminal formatting and tables

Testing

Test Coverage

  • Unit tests: tests/cli/test_interactive_cli.py
  • Integration tests: tests/cli/test_interactive.py
  • Command tests: tests/cli/test_basic_commands.py

Key Test Cases

  1. Interactive Mode Tests (test_interactive_cli.py:23-145): Tests CLI initialization and commands
  2. Basic Mode Tests (test_basic_commands.py:15-89): Tests basic mode functionality
  3. Help System Tests (test_help_regressions.py:12-67): Tests help text generation

Error Handling

Exception Types

  • ProviderError (error_handler.py:23): Provider initialization failures
  • ConfigurationError (error_handler.py:34): Missing configuration
  • KeyboardInterrupt: Handled for clean exit (interactive_cli.py:589)

Error Flow

# From error_handler.py:20-65
try:
    provider = initialize_provider()
except ProviderError as e:
    self.display_error(e)  # User-friendly error display

Performance Considerations

  1. Lazy Loading: Commands loaded on-demand (command_registry.py:69)
  2. Streaming Responses: AI responses streamed character by character (chat_session.py:73-98)
  3. Async I/O: Interactive mode uses async for responsiveness

Security Considerations

  1. No Credential Storage: API keys read from environment variables
  2. Path Validation: File paths validated before operations
  3. Command Injection: No shell command execution without explicit tools

Examples

Basic Usage

# One-shot query
coda chat "What is Python?"

# Interactive mode
coda chat

# With specific provider
coda chat --provider ollama --model llama3

Advanced Usage

# From tests/cli/test_interactive_cli.py:45
cli = InteractiveCLI(
    provider=mock_provider,
    config=config,
    theme=Theme.get_theme("monokai")
)
result = await cli.process_slash_command("/help")

Integration Points

With Other Modules

  1. Provider Module: Called from provider_manager.py:19-37
  2. Session Module: Integrated in interactive_cli.py:217-245
  3. Agent Module: Used in agent_chat.py:34-56
  4. Theme Module: Applied throughout UI rendering

Extension Points

  1. New Commands: Add to command_registry.py registry
  2. New Modes: Extend shared/modes.py enums
  3. Custom Completers: Implement completer in interactive_cli.py

Known Limitations

  1. Windows Support: Limited prompt-toolkit features on Windows (see main.py:45 comment)
  2. Emoji Rendering: Requires terminal with emoji support (see theme_selector.py:23)

Verification Checklist

  • All file paths verified to exist
  • All line numbers checked for accuracy
  • All class/function names validated
  • Code snippets verified from source
  • Diagrams match actual code structure
  • Examples tested from test files
  • Cross-references to other modules verified
  • Configuration options match actual usage

References

Related Documentation

Source Files

All files referenced in this document:

  • coda/cli/main.py
  • coda/cli/interactive_cli.py
  • coda/cli/command_registry.py
  • coda/cli/chat_session.py
  • coda/cli/provider_manager.py
  • coda/cli/shared/commands.py
  • coda/cli/shared/modes.py
  • tests/cli/test_interactive_cli.py
  • tests/cli/test_basic_commands.py

Clone this wiki locally