# ther1d/shell_gpt architecture

> Architecture diagram of the GitHub repository ther1d/shell_gpt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ther1d/shell_gpt
- Repository: https://github.com/ther1d/shell_gpt

## Overview

##### Project Type and Purpose
- ShellGPT is an open-source, Python-based command-line productivity tool that wraps calls to LLMs (OpenAI or local backends) to generate shell commands, code snippets, documentation, or drive REPL/chat sessions.
- It’s delivered as a pip-installable CLI (`sgpt`), but also provides Docker support and shell-integration plugins.

##### High-Level File Structure Analysis
Top-level artifacts:
– Dockerfile, .devcontainer/, GitHub workflows (CI, lint, tests, releases).
– pyproject.toml: Python packaging.
– scripts/: formatting, linting, testing helpers.
– sgpt/: core Python package.
– tests/: unit & integration tests.

Inside sgpt/:
– __main__.py & app.py: CLI entrypoints & orchestration.
– config.py: runtime configuration loader.
– cache.py: request & chat cache management.
– handlers/: concrete handler classes (default, chat, REPL, shell). Implements Strategy pattern to dispatch user commands.
– integration.py: wrapper around LLM API calls (OpenAI or local via API_BASE_URL or LiteLLM).
– llm_functions/: built-in function definitions (plugin architecture) that can be called by the LLM.
– role.py: role management for system prompts.
– utils.py & function.py: shared utilities and function-calling framework.

##### Key README Insights
- CLI flags map to handlers (–shell ⇒ ShellHandler; –code ⇒ DefaultHandler in code mode; –chat / –repl ⇒ ChatHandler/ReplHandler).
- Supports “function calling” via pluggable modules under llm_functions/.
- Caching layer avoids duplicate API requests.
- Supports local LLMs via LiteLLM/Ollama or remote OpenAI.

##### Main Components
a. CLI Layer
– sgpt CLI entrypoint
– Argument parser

b. Core Orchestration
– App (sgpt/app.py): loads config, initializes cache & roles, dispatches to handler.
– Config Manager (sgpt/config.py)
– Cache Manager (sgpt/cache.py)

c. Handlers (Strategy Pattern)
– DefaultHandler (code snippets, documentation)
– ChatHandler / ReplHandler (conversational session)
– ShellHandler (generates/executes commands)

d. LLM Integration Layer
– Integration module (sgpt/integration.py): abstracts OpenAI vs local LLM backends
– Function-calling dispatcher (sgpt/function.py): selects & executes llm_functions

e. Plugin Layer
– llm_functions/common & OS-specific (mac/apple_script.py)
– Custom user functions (loaded from OPENAI_FUNCTIONS_PATH)

f. Printer & Output

g. External Services
– OpenAI API or local LLM server (Ollama)
– Shell environment (for execution, shell integration hooks)

h. Persistence
– File-based chat cache and request cache (typically under ~/.config/shell_gpt or container volume)

##### Relationships & Data Flow
1. User invokes `sgpt [flags] "prompt"` or pipes stdin → CLI entrypoint
2. Parser passes arguments → App
3. App loads Config & Cache, registers Roles
4. App selects appropriate Handler based on flags
5. Handler builds request payload (prompt + role + conversation history)
6. Integration layer sends request to LLM backend → receives response
7. If response includes function calls → Function dispatcher loads the matching llm_function plugin → executes locally → returns result to Integration → LLM invoked again if needed
8. Response passed to Printer → outputs to STDOUT (or executes shell commands if ShellHandler interactive)
9. Cache Manager persists prompts & responses

##### Architectural Patterns & Principles
- Layered architecture: CLI → Core → Handlers → Integration → External
- Plugin architecture for both handlers (Strategy) and functions (PLUGINS)
- Single Responsibility: each module has a clear purpose (config, cache, handlers, integration, printing)
- Extensibility: new handlers and llm_functions can be dropped into their directories without changing core code

##### Essential Elements
– Clear labels: module names and responsibilities
– Annotations for plugin directories (handlers, llm_functions) to highlight extensibility points

## Diagram (Mermaid)

```mermaid
graph TB
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entrypoint\nsgpt/__main__.py"]:::core
        Parser["Argument Parser\nsgpt/app.py"]:::core
    end

    %% Core Orchestration
    subgraph "Core Orchestration"
        App["App Orchestrator\nsgpt/app.py"]:::core
        Config["Config Manager\nsgpt/config.py"]:::core
        Cache["Cache Manager\nsgpt/cache.py"]:::core
        Role["Role Management\nsgpt/role.py"]:::core
    end

    %% Handlers
    subgraph "Handlers (Strategy Pattern)"
        BaseHandler["Handler Base Class\nsgpt/handlers/handler.py"]:::handlers
        DefaultHandler["DefaultHandler\nsgpt/handlers/default_handler.py"]:::handlers
        ChatHandler["ChatHandler\nsgpt/handlers/chat_handler.py"]:::handlers
        ReplHandler["ReplHandler\nsgpt/handlers/repl_handler.py"]:::handlers
        ShellHandler["ShellHandler\nsgpt/handlers/shell_handler.py"]:::handlers
    end

    %% Integration Layer
    subgraph "Integration Layer"
        Integration["Integration Module\nsgpt/integration.py"]:::integration
        FunctionDispatcher["Function Dispatcher\nsgpt/function.py"]:::integration
    end

    %% Function Plugins
    subgraph "Function Plugins"
        InitFuncs["Init Functions\nsgpt/llm_functions/init_functions.py"]:::integration
        CommonFunc["Common ExecShell\nsgpt/llm_functions/common/execute_shell.py"]:::integration
        MacFunc["macOS Plugin\nsgpt/llm_functions/mac/apple_script.py"]:::integration
    end

    %% Printer
    Printer["Printer\nsgpt/printer.py"]:::core

    %% External Services
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        LocalLLM["Local LLM Server"]:::external
        ShellEnv["Shell Environment"]:::external
        FileSys["File System (Cache)"]:::external
    end

    %% Data Flow
    CLI -->|invoke| Parser
    Parser -->|passes args| App
    App --> Config
    App --> Cache
    App --> Role
    App -->|selects| BaseHandler
    BaseHandler --> DefaultHandler
    BaseHandler --> ChatHandler
    BaseHandler --> ReplHandler
    BaseHandler --> ShellHandler
    DefaultHandler -->|builds payload| Integration
    ChatHandler -->|builds payload| Integration
    ReplHandler -->|builds payload| Integration
    ShellHandler -->|builds payload| Integration
    Integration -->|APIrequest| OpenAI
    Integration -->|APIrequest| LocalLLM
    Integration -->|response| FunctionDispatcher
    FunctionDispatcher -->|loads plugin| InitFuncs
    FunctionDispatcher -->|loads plugin| CommonFunc
    FunctionDispatcher -->|loads plugin| MacFunc
    FunctionDispatcher -->|returns result| Integration
    Integration -->|response| DefaultHandler
    Integration -->|response| ChatHandler
    Integration -->|response| ReplHandler
    Integration -->|response| ShellHandler
    DefaultHandler -->|output| Printer
    ChatHandler -->|output| Printer
    ReplHandler -->|output| Printer
    ShellHandler -->|executes| ShellEnv
    Cache -->|persists| FileSys

    %% Click Events
    click CLI "https://github.com/ther1d/shell_gpt/blob/main/sgpt/__main__.py"
    click Parser "https://github.com/ther1d/shell_gpt/blob/main/sgpt/app.py"
    click App "https://github.com/ther1d/shell_gpt/blob/main/sgpt/app.py"
    click Config "https://github.com/ther1d/shell_gpt/blob/main/sgpt/config.py"
    click Cache "https://github.com/ther1d/shell_gpt/blob/main/sgpt/cache.py"
    click Role "https://github.com/ther1d/shell_gpt/blob/main/sgpt/role.py"
    click BaseHandler "https://github.com/ther1d/shell_gpt/blob/main/sgpt/handlers/handler.py"
    click DefaultHandler "https://github.com/ther1d/shell_gpt/blob/main/sgpt/handlers/default_handler.py"
    click ChatHandler "https://github.com/ther1d/shell_gpt/blob/main/sgpt/handlers/chat_handler.py"
    click ReplHandler "https://github.com/ther1d/shell_gpt/blob/main/sgpt/handlers/repl_handler.py"
    click Integration "https://github.com/ther1d/shell_gpt/blob/main/sgpt/integration.py"
    click FunctionDispatcher "https://github.com/ther1d/shell_gpt/blob/main/sgpt/function.py"
    click InitFuncs "https://github.com/ther1d/shell_gpt/blob/main/sgpt/llm_functions/init_functions.py"
    click CommonFunc "https://github.com/ther1d/shell_gpt/blob/main/sgpt/llm_functions/common/execute_shell.py"
    click MacFunc "https://github.com/ther1d/shell_gpt/blob/main/sgpt/llm_functions/mac/apple_script.py"
    click Printer "https://github.com/ther1d/shell_gpt/blob/main/sgpt/printer.py"

    %% Styles
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef handlers fill:#90ee90,stroke:#333,stroke-width:1px
    classDef integration fill:#ffa500,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
