# supermk15/openagentcli architecture

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

- Interactive diagram: https://gitdiagram.com/supermk15/openagentcli
- Repository: https://github.com/supermk15/openagentcli

## Overview

##### Project Type and Purpose
- This is a Python-based command-line coding agent (“OpenAgentCLI”) that provides an interactive shell for multi-step reasoning, native tool invocation, and AI-powered chat via an external provider (Cohere). It bundles a local MCP server to manage tool definitions and runs everything through a unified CLI entry point.

##### File Structure
- Top-level:
- setup.py, README.md, config.yaml – packaging, documentation, user config
- openagentcli/ – the core package
- Inside openagentcli/:
- models/ – BaseModel and CohereModel implementations
- protocol/ – ProtocolAdapter interface and provider-specific adapters
- server/ – MCP server implementation (mcp_server.py)
- chat_storage.py, config.py, diff_utils.py – utility modules
- tool_executor.py, tool_display.py – core tool invocation logic
- ui.py, main.py – CLI interface and entry point

##### Extract Key Architecture Insights From README
- Model adapters follow the Adapter pattern to translate between internal Message/ToolDefinition formats and provider APIs.
- The MCP server (FastMCP) exposes tool endpoints; the CLI invokes tools either natively or via the server.
- Configuration (model selection, custom instructions) is externalized in config.yaml/.env.

##### Main Components
a. CLI Frontend (main.py + ui.py): reads user input, renders output, accepts slash-commands.
b. Configuration Loader (config.py + config.yaml/.env): resolves API keys and model selection.
c. Chat Storage (chat_storage.py): maintains conversation history.
d. Tool Executor & Display (tool_executor.py, tool_display.py): defines and invokes local shell and file tools.
e. Protocol Layer (protocol/adapter.py + provider adapters): maps internal messages/tools ↔ provider formats.
f. Model Implementations (models/base.py + cohere_model.py): core chat logic encapsulating API calls.
g. MCP Server (server/mcp_server.py): registers tool definitions as HTTP/gRPC endpoints via FastMCP.
h. External AI Service (Cohere API): remote provider invoked by the model.

##### Relationships and Data Flows
- User types in CLI → UI module parses → selected command:
- Chat command: → load config → chat storage → Protocol Adapter → Model → External API → Adapter → chat storage → UI
- Tool command: → Tool Executor → local file system or shell → return → UI
- Multi‐step: Model issues tool calls → MCP Server endpoint → Executor → result back to Model

##### Architectural Patterns & Design Principles
- Adapter Pattern (protocol adapters) for provider abstraction
- Dependency Injection (models receive adapter instances)
- Separation of Concerns (UI vs. core logic vs. I/O vs. external API)
- Plugin-style extensibility (add new models/adapters in protocol/, new tools via server registration)

##### Technologies & Frameworks to Annotate
- Python 3.X
- FastMCP (server framework)
- Cohere API (external chat provider)
- YAML/.env for config
- Standard library for subprocess, file I/O, regex

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User([User]):::external

    %% UI & Frontend Layer
    subgraph "UI & Frontend"
        Main["main.py"]:::frontend
        UIComp["ui.py"]:::frontend
    end

    %% Configuration Loader
    Config["Configuration Loader\n(config.py)"]:::core
    ConfigYAML["config.yaml"]:::core

    %% Chat Storage
    ChatStorage[(Chat Storage)]:::storage

    %% Protocol Layer
    subgraph "Protocol Layer"
        AdapterInterface["adapter.py"]:::core
        CohereAdapter["cohere_adapter.py"]:::core
        AdapterTypes["types.py"]:::core
    end

    %% Model Implementations
    subgraph "Model Implementations"
        BaseModel["base.py"]:::core
        CohereModel["cohere_model.py"]:::core
    end

    %% MCP Server
    MCPServer["mcp_server.py"]:::core

    %% Tool Executor & Display
    ToolExec["tool_executor.py"]:::core
    ToolDisplay["tool_display.py"]:::core

    %% Utilities
    DiffUtils["diff_utils.py"]:::util

    %% Packaging & Docs
    Setup["setup.py"]:::util
    Readme["README.md"]:::util

    %% External Services
    CohereAPI([Cohere API]):::external

    %% Main Flows
    User -->|types command| Main
    Main -->|renders prompt| UIComp

    %% Chat Command Flow
    UIComp -->|"/chat"| Config
    ConfigYAML -.->|metadata| Config
    Config -->|"settings"| ChatStorage
    ChatStorage -->|"Message[]"| AdapterInterface
    AdapterInterface -->|"ToolDefinition/Message ↔ API"| CohereAdapter
    AdapterInterface --> AdapterTypes
    CohereAdapter -->|"API Request"| CohereAPI
    CohereAPI -->|"API Response"| CohereAdapter
    CohereAdapter -->|"Message[]"| AdapterInterface
    AdapterInterface -->|"Message[]"| ChatStorage
    ChatStorage -->|"history"| UIComp

    %% Tool Command Flow
    UIComp -->|"/tool"| ToolExec
    ToolExec -->|"exec shell/FS"| ToolExec
    ToolExec -->|"ToolResult"| ToolDisplay
    ToolDisplay -->|"output"| UIComp

    %% Multi-step Tool via MCP
    CohereModel -->|tool call| MCPServer
    MCPServer -->|HTTP/gRPC| ToolExec
    ToolExec -->|result| MCPServer
    MCPServer -->|result| CohereModel

    %% Model Hookup
    AdapterInterface -->|inject adapter| BaseModel
    CohereAdapter -->|implements| BaseModel
    BaseModel -->|subclass| CohereModel

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#333,stroke-width:1px
    classDef core fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef util fill:#CFD8DC,stroke:#333,stroke-width:1px
    classDef storage fill:#E1BEE7,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px

    %% Click Events
    click Main "https://github.com/supermk15/openagentcli/blob/main/openagentcli/main.py"
    click UIComp "https://github.com/supermk15/openagentcli/blob/main/openagentcli/ui.py"
    click Config "https://github.com/supermk15/openagentcli/blob/main/openagentcli/config.py"
    click ConfigYAML "https://github.com/supermk15/openagentcli/blob/main/config.yaml"
    click ChatStorage "https://github.com/supermk15/openagentcli/blob/main/openagentcli/chat_storage.py"
    click ToolExec "https://github.com/supermk15/openagentcli/blob/main/openagentcli/tool_executor.py"
    click ToolDisplay "https://github.com/supermk15/openagentcli/blob/main/openagentcli/tool_display.py"
    click AdapterInterface "https://github.com/supermk15/openagentcli/blob/main/openagentcli/protocol/adapter.py"
    click CohereAdapter "https://github.com/supermk15/openagentcli/blob/main/openagentcli/protocol/cohere_adapter.py"
    click AdapterTypes "https://github.com/supermk15/openagentcli/blob/main/openagentcli/protocol/types.py"
    click BaseModel "https://github.com/supermk15/openagentcli/blob/main/openagentcli/models/base.py"
    click CohereModel "https://github.com/supermk15/openagentcli/blob/main/openagentcli/models/cohere_model.py"
    click MCPServer "https://github.com/supermk15/openagentcli/blob/main/openagentcli/server/mcp_server.py"
    click DiffUtils "https://github.com/supermk15/openagentcli/blob/main/openagentcli/diff_utils.py"
    click Setup "https://github.com/supermk15/openagentcli/blob/main/setup.py"
    click Readme "https://github.com/supermk15/openagentcli/blob/main/README.md"
```
