# matheusml/zsh-ai architecture

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

- Interactive diagram: https://gitdiagram.com/matheusml/zsh-ai
- Repository: https://github.com/matheusml/zsh-ai

## Overview

##### Project type and purpose
- This is an open-source, lightweight zsh plugin (“zsh-ai”) that lives entirely in the terminal.
- Purpose: Transform natural-language prompts into shell commands by calling either a cloud AI (Anthropic Claude) or a local model (Ollama).

##### File structure
Top-level:
- zsh-ai.plugin.zsh – plugin entrypoint that hooks into zsh.
- lib/ – core library modules, each implemented as a separate .zsh file:
– config.zsh       • loads/validates environment variables
– context.zsh      • inspects cwd/git status to build prompt context
– utils.zsh        • JSON escaping, helper functions
– widget.zsh       • zle widget that binds “#” to trigger AI call
– providers/       • anthropic.zsh & ollama.zsh implement two pluggable backends
- tests/ – unit tests for each module, ensuring reliability
- .github/workflows/test.yml – CI pipeline that runs tests on push

##### README for additional insights
- Core flow: user types “# some task” → widget intercepts → context + config assembled → provider module formats request → sends to Anthropic API or local Ollama endpoint → parses JSON → returns a shell command → prints into the shell.
- No external dependencies aside from optional jq for JSON parsing.

##### Detail without over-splitting
- Module but group low-level helpers (utils, JSON escape) under “Utility layer.”
- Both provider paths (Anthropic vs. Ollama) branching from a common “Provider” interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "User & Shell Layer"
        direction TB
        User(("User")):::ui
        ZSHShell["zsh Shell (ZLE)"]:::ui
    end

    %% EntryPoint
    PluginEntrypoint["Plugin Entrypoint"]:::core
    click PluginEntrypoint "https://github.com/matheusml/zsh-ai/blob/main/zsh-ai.plugin.zsh"

    User -->|types prompt| ZSHShell
    ZSHShell -->|loads plugin| PluginEntrypoint
    PluginEntrypoint -->|registers widget| Widget

    %% Core Logic
    subgraph "Core Logic" 
        direction TB
        Widget["Widget Module"]:::core
        Config["Config Module"]:::core
        Context["Context Module"]:::core
        Utility["Utility Layer"]:::core
    end
    click Widget "https://github.com/matheusml/zsh-ai/blob/main/lib/widget.zsh"
    click Config "https://github.com/matheusml/zsh-ai/blob/main/lib/config.zsh"
    click Context "https://github.com/matheusml/zsh-ai/blob/main/lib/context.zsh"
    click Utility "https://github.com/matheusml/zsh-ai/blob/main/lib/utils.zsh"

    PluginEntrypoint --> Widget
    Widget -->|gather env| Config
    Widget -->|inspect cwd/git| Context
    Widget -->|helper functions| Utility

    %% Environment Variables
    Env["Environment Variables"]:::optional
    Env --> Config
    Env --> ProviderInterface

    %% Provider Interface & Modules
    ProviderInterface["Provider Interface"]:::provider
    Widget -->|build request| ProviderInterface

    subgraph "Providers" 
        direction TB
        Anthropic["Anthropic Provider"]:::provider
        Ollama["Ollama Provider"]:::provider
    end
    click Anthropic "https://github.com/matheusml/zsh-ai/blob/main/lib/providers/anthropic.zsh"
    click Ollama "https://github.com/matheusml/zsh-ai/blob/main/lib/providers/ollama.zsh"

    ProviderInterface --> Anthropic
    ProviderInterface --> Ollama

    %% External Services
    subgraph "External AI Services" 
        direction TB
        AnthropicAPI[(Anthropic Claude API)]:::external
        OllamaServer[(Ollama Server)]:::external
    end

    Anthropic -->|HTTP request| AnthropicAPI
    Ollama -->|Local HTTP call| OllamaServer

    %% Response Flow
    AnthropicAPI -->|JSON response| Utility
    OllamaServer -->|JSON response| Utility
    Utility -->|format string| Widget
    Widget -->|echo command| ZSHShell

    %% Optional jq
    JQ[(jq)]:::optional
    Utility -->|optional parsing| JQ

    %% CI / Testing
    subgraph "CI & Tests" 
        direction TB
        Tests["Unit Tests"]:::ci
        GitHubActions["GitHub Actions CI"]:::ci
    end
    click GitHubActions "https://github.com/matheusml/zsh-ai/blob/main/.github/workflows/test.yml"

    Tests -->|run on push| GitHubActions
    GitHubActions --> Tests

    %% Styles
    classDef ui fill:#D6EFFF,stroke:#1E90FF,color:#000;
    classDef core fill:#FFF4CC,stroke:#FFD700,color:#000;
    classDef provider fill:#E6F7E6,stroke:#28A745,color:#000;
    classDef external fill:#F0E6FF,stroke:#6F42C1,color:#000;
    classDef optional fill:#F8F9FA,stroke:#6C757D,stroke-dasharray: 5 5,color:#000;
    classDef ci fill:#E2E3E5,stroke:#ADB5BD,color:#000;
```
