# answerdotai/shell_sage architecture

> Architecture diagram of the GitHub repository answerdotai/shell_sage, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/answerdotai/shell_sage
- Repository: https://github.com/answerdotai/shell_sage

## Overview

##### Main Components

a) Client-Side Components:
- Terminal Environment (tmux)
- ShellSage CLI Interface
- Configuration Management System
- Terminal Context Collector

b) Core Processing Components:
- Command Parser
- Context Analyzer
- Model Interface Layer

c) External Services:
- LLM Providers (Claude/OpenAI/Alternative Models)
- Local Model Support (Ollama)

##### Key Relationships to Highlight

- User → Terminal → ShellSage CLI
- ShellSage CLI → Context Collector → tmux Integration
- Context Collector → Model Interface Layer
- Model Interface Layer → LLM Providers
- Configuration System → All Components

##### Specific Implementation Details

- Pane Management System (for tmux integration)
- Command Pipeline Processing
- Configuration Handler (for shell_sage.conf)
- Model Provider Abstraction Layer

##### Component Details

Core Module (core.py):
- Connections to both input and output systems

Config Module (config.py):
- As a supporting system
- Connections to all configurable components

##### Architectural Patterns to Emphasize

- Plugin Architecture (for different model providers)
- Pipeline Pattern (for command processing)
- Observer Pattern (for tmux pane monitoring)

##### Technical Elements

Specific technical details:
- Environment Variables Integration
- API Key Management
- tmux Configuration Integration
- File System Interaction Points

##### Configuration Layer (Side)

- Keep the focus on the interaction between tmux and the LLM providers
- Extensibility points for different model providers
- Clear separation between configuration and runtime components
- Error handling and fallback paths
- Document the async/sync boundaries in the system

- Component groupings
- Configuration points
- External dependency markers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and Classes
    classDef ui fill:#FFE5CC,stroke:#FF9933
    classDef core fill:#CCE5FF,stroke:#3399FF
    classDef external fill:#D9F2D9,stroke:#47A347
    classDef config fill:#E6E6E6,stroke:#808080
    classDef pipeline fill:#FFE6FF,stroke:#FF99FF

    %% User Interface Layer
    subgraph UI
        Terminal["Terminal Environment"]:::ui
        TmuxEnv["tmux Environment"]:::ui
        CLI["ShellSage CLI"]:::ui
    end

    %% Core Processing Layer
    subgraph Processing
        CmdParser["Command Parser"]:::core
        CtxAnalyzer["Context Analyzer"]:::core
        ModelInterface["Model Interface Layer"]:::core
        PaneMgmt["Pane Management System"]:::core
        CoreProc["Core Processing Unit"]:::core
    end

    %% External Services Layer
    subgraph ExternalServices
        Claude["Claude API"]:::external
        OpenAI["OpenAI API"]:::external
        Ollama["Ollama Local Model"]:::external
    end

    %% Configuration Layer
    subgraph ConfigSystem
        ConfigMgr["Configuration Manager"]:::config
        EnvVars["Environment Variables"]:::config
        APIKeys["API Key Management"]:::config
        TmuxConfig["Tmux Configuration"]:::config
    end

    %% Relationships
    Terminal --> TmuxEnv
    TmuxEnv --> CLI
    CLI --> CmdParser
    CmdParser --> CtxAnalyzer
    CtxAnalyzer --> CoreProc
    CoreProc --> ModelInterface
    ModelInterface --> Claude
    ModelInterface --> OpenAI
    ModelInterface --> Ollama
    ConfigMgr --> ModelInterface
    ConfigMgr --> CLI
    ConfigMgr --> TmuxConfig
    APIKeys --> ModelInterface
    PaneMgmt --> TmuxEnv

    %% Click Events
    click CoreProc "https://github.com/AnswerDotAI/shell_sage/blob/main/shell_sage/core.py"
    click ConfigMgr "https://github.com/AnswerDotAI/shell_sage/blob/main/shell_sage/config.py"
    click TmuxConfig "https://github.com/AnswerDotAI/shell_sage/blob/main/.tmux.conf"
    click CLI "https://github.com/AnswerDotAI/shell_sage/blob/main/shell_sage/__init__.py"
    click ModelInterface "https://github.com/AnswerDotAI/shell_sage/blob/main/shell_sage/_modidx.py"

    %% Legend
    subgraph Legend
        UI_Legend["User Interface"]:::ui
        Core_Legend["Core Components"]:::core
        External_Legend["External Services"]:::external
        Config_Legend["Configuration"]:::config
    end
```
