# cloi-ai/cloi architecture

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

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

## Overview

##### Project type and purpose
- Cloi CLI is a local, context-aware debugging agent that runs entirely in the terminal. It’s an open-source CLI tool written in Node.js (with some Python helpers) that uses a local Ollama LLM to analyze errors and apply patches to the codebase.

##### File structure
- Top-level “bin/” folder holds the entrypoint scripts for installation (“cloi-setup.cjs”, “index.js”, plus Python setup).
- “src/” is divided into four main subdirectories:
- cli/ – handles parsing of terminal commands and interactive session loop.
- core/ – implements the main debugging pipeline (command orchestration, LLM calls, patch generation, error traceback analysis).
- utils/ – miscellaneous helpers (file I/O, command history, Ollama API wrappers in Python/JS, optimization, temp script management).
- There are configuration files (package.json, requirements.txt) and setup scripts that ensure both Node.js and Python runtimes are ready.

##### README for additional insights
- Confirms 100% local operation, no external API keys, integrates with Ollama locally installed models, and provides interactive slash commands (/debug, /model, /history, /help).
- Mentions internal architecture changes (structured outputs, history/traceback refactors), pointing to modular separation between core logic and utilities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External User Input
    User["User Terminal"]:::external

    %% Bootstrap Scripts
    subgraph "bin/"
        Setup1["cloi-setup.cjs"]:::internal
        Setup2["ollama-setup.cjs"]:::internal
        Setup3["ollama_setup.py"]:::internal
        Req["requirements.txt"]:::internal
        Index["index.js"]:::internal
    end

    %% CLI Layer
    Ctrl["CLI Controller\n(src/cli/index.js)"]:::internal

    %% Core Debugging Engine
    subgraph "Core Debugging Engine"
        CO["Command Orchestrator\n(src/core/command.js)"]:::internal
        TA["Traceback Analyzer\n(src/core/traceback.js)"]:::internal
        LL["LLM Interface\n(src/core/llm.js)"]:::internal
        PG["Patch Generator\n(src/core/patch.js)"]:::internal
    end

    %% UI Layer
    subgraph "UI Layer"
        BX["Box Layout\n(src/ui/boxen.js)"]:::internal
        PR["Prompt Handler\n(src/ui/prompt.js)"]:::internal
    end

    %% Utility Layer
    subgraph "Utility Layer"
        FIO["File I/O\n(src/utils/file.js)"]:::internal
        HIST["History\n(src/utils/history.js)"]:::internal
        OC["Ollama Wrapper\n(src/utils/ollama_call.py)"]:::internal
        OPT["Optimization\n(src/utils/optimization.js)"]:::internal
        TMP["Temp Script\n(src/utils/tempscript.js)"]:::internal
    end

    %% External Dependencies
    Node["Node.js Runtime"]:::external
    Py["Python Runtime"]:::external
    Ollama["Ollama Service"]:::external
    FS["File System"]:::storage

    %% Data Flows
    User --> Index
    Index --> Ctrl
    Ctrl --> CO
    CO --> TA
    TA --> CO
    CO --> LL
    LL --> PG
    PG --> FIO
    PG --> TMP
    PG --> BX
    PG --> PR
    PR --> FIO
    PR --> HIST

    %% Storage Flows
    FIO --> FS
    TMP --> FS
    HIST --> FS

    %% External Integrations
    Index --> Node
    OC --> Py
    LL --> Ollama

    %% Click Events
    click Setup1 "https://github.com/cloi-ai/cloi/blob/main/bin/cloi-setup.cjs"
    click Setup2 "https://github.com/cloi-ai/cloi/blob/main/bin/ollama-setup.cjs"
    click Setup3 "https://github.com/cloi-ai/cloi/blob/main/bin/ollama_setup.py"
    click Req "https://github.com/cloi-ai/cloi/blob/main/bin/requirements.txt"
    click Index "https://github.com/cloi-ai/cloi/blob/main/bin/index.js"
    click Ctrl "https://github.com/cloi-ai/cloi/blob/main/src/cli/index.js"
    click CO "https://github.com/cloi-ai/cloi/blob/main/src/core/command.js"
    click TA "https://github.com/cloi-ai/cloi/blob/main/src/core/traceback.js"
    click PG "https://github.com/cloi-ai/cloi/blob/main/src/core/patch.js"
    click LL "https://github.com/cloi-ai/cloi/blob/main/src/core/llm.js"
    click BX "https://github.com/cloi-ai/cloi/blob/main/src/ui/boxen.js"
    click PR "https://github.com/cloi-ai/cloi/blob/main/src/ui/prompt.js"
    click FIO "https://github.com/cloi-ai/cloi/blob/main/src/utils/file.js"
    click HIST "https://github.com/cloi-ai/cloi/blob/main/src/utils/history.js"
    click OC "https://github.com/cloi-ai/cloi/blob/main/src/utils/ollama_call.py"
    click OPT "https://github.com/cloi-ai/cloi/blob/main/src/utils/optimization.js"
    click TMP "https://github.com/cloi-ai/cloi/blob/main/src/utils/tempscript.js"

    %% Styles
    classDef internal fill:#E0F7FA,stroke:#0277BD,color:#01579B;
    classDef external fill:#C8E6C9,stroke:#2E7D32,color:#1B5E20;
    classDef storage fill:#EEEEEE,stroke:#757575,color:#424242;
```
