# shareai-lab/mini_kode architecture

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

- Interactive diagram: https://gitdiagram.com/shareai-lab/mini_kode
- Repository: https://github.com/shareai-lab/mini_kode

## Overview

##### Project type and purpose
- This is a minimal “mini Kode” CLI agent tool (an open-source tool) with two iterations:
- v1_basic_agent.py – model-as-agent loop with four core tools (bash, read_file, write_file, edit_text).
- v2_todo_agent.py – adds a structured Todo toolchain and system-reminder mechanism for explicit planning and self-supervision.
- Supplementary “articles” folder holds documentation drafts; “demo” folder contains standalone game demos (HTML/JS/Python) for showcasing graphics and physics utilities but is not part of the core CLI workflow.

##### File structure
- Top-level:
- README.md / README_en.md – project overview and architecture explanation.
- requirements.txt – Python dependencies (e.g., OpenAI SDK).
- v1_basic_agent.py & v2_todo_agent.py – main entry points for each version.
- “articles/” – Markdown documentation versions.
- “demo/” – independent web & Python demos illustrating UI, graphics, physics, AI in browser or CLI simulations.
- No separate “src” or “lib” folder; Python scripts encapsulate both core logic and tool implementations.

##### README for additional insights
- v1 workflow: CLI ↔ LLM via OpenAI API ↔ tool dispatcher ↔ filesystem & shell commands.
- Architectural patterns: tool-dispatching agent loop, self-supervising through structured external memory (Todo list), separation of prompts, tools, and I/O.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    UserCLI["User CLI Interface"]:::io

    %% Agent Core
    Agent["Agent Controller"]:::core
    Spinner["Spinner (Thread)"]:::core
    Agent --> Spinner

    %% LLM Client
    LLM["LLM Client<br/>(OpenAI ChatCompletion)"]:::core

    %% Tool Dispatcher
    Dispatcher["Tool Dispatcher"]:::core
    PromptBuilder["Prompt Builder"]:::core
    SafetyChecks["Sanitization & Safety"]:::core
    Agent --> LLM
    LLM --> Dispatcher
    Dispatcher --> PromptBuilder
    Dispatcher --> SafetyChecks

    %% Core Tools Subgraph
    subgraph "Core Tools" 
        direction TB
        BashTool["Bash Tool"]:::tool
        ReadFile["Read File Tool"]:::tool
        WriteFile["Write File Tool"]:::tool
        EditText["Edit Text Tool"]:::tool
    end

    %% v2 Tools Subgraph
    subgraph "v2 Tools (Extensions)" 
        direction TB
        TodoManager["TodoManager"]:::v2
        TodoWrite["TodoWrite Tool"]:::v2
        ReminderInjector["Reminder Injector"]:::v2
        ConsoleRenderer["Console Renderer"]:::v2
    end

    %% External Resources
    FS[(File System)]:::ext
    Shell[(Shell Environment)]:::ext
    TodoList[(Todo List Storage)]:::ext

    %% Demo Modules
    Demo["Demo Modules"]:::demo

    %% Documentation & Config
    subgraph "Project Docs & Config"
        direction TB
        README["README.md"]:::doc
        READMEen["README_en.md"]:::doc
        Req["requirements.txt"]:::doc
        ArtV1["articles/v1文章.md"]:::doc
        ArtV2["articles/v2文章.md"]:::doc
    end

    %% Core Loop Connections
    UserCLI --> Agent
    Dispatcher -->|invokes| BashTool
    Dispatcher -->|invokes| ReadFile
    Dispatcher -->|invokes| WriteFile
    Dispatcher -->|invokes| EditText
    BashTool --> FS
    ReadFile --> FS
    WriteFile --> FS
    EditText --> FS
    Dispatcher -->|invokes| TodoManager
    Dispatcher -->|invokes| TodoWrite
    Dispatcher -->|invokes| ReminderInjector
    TodoWrite --> TodoList
    ReminderInjector --> TodoList
    TodoManager --> TodoList
    Dispatcher -->|renders| ConsoleRenderer
    ConsoleRenderer --> UserCLI
    Dispatcher --> Agent
    Agent --> UserCLI

    %% Demo Modules (separate)
    Demo -.-> Dispatcher

    %% Click Events
    click README "https://github.com/shareai-lab/mini_kode/blob/main/README.md"
    click READMEen "https://github.com/shareai-lab/mini_kode/blob/main/README_en.md"
    click Req "https://github.com/shareai-lab/mini_kode/blob/main/requirements.txt"
    click ArtV1 "https://github.com/shareai-lab/mini_kode/blob/main/articles/v1文章.md"
    click ArtV2 "https://github.com/shareai-lab/mini_kode/blob/main/articles/v2文章.md"
    click Demo "https://github.com/shareai-lab/mini_kode/tree/main/demo/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef tool fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ext fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef v2 fill:#FFA500,stroke:#333,stroke-width:1px
    classDef io fill:#E6E6FA,stroke:#333,stroke-width:1px
    classDef demo fill:#F5F5F5,stroke:#333,stroke-width:1px
    classDef doc fill:#FFE4E1,stroke:#333,stroke-width:1px
```
