# shareai-lab/kode architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-featured CLI application (“Kode”) with a layered, plugin-style architecture.
- Purpose: Provide an AI-driven terminal assistant that understands codebases, runs shell commands, edits files, and orchestrates AI sub-agents across multiple AI model providers.

##### High-Level Component Breakdown
a. Entrypoints
- CLI layer (src/entrypoints/cli.tsx, mcp.ts)
- Docker wrapper (Dockerfile, DEPLOYMENT_GUIDE.md)
b. Command Processor
- Command registry (src/commands.ts)
- Individual commands/modules (src/commands/\*.tsx/.ts)
c. Context & State Manager
- Conversation/context manager (src/context.ts, src/utils/messageContextManager.ts)
- Session state, history (src/history.ts, src/utils/sessionState.ts)
d. Model Management Layer
- ModelManager & profiles (services/adapters + src/services/modelAdapterFactory.ts)
- Multi-model pointers & switching logic (Configuration in src/constants and CLI `/model`)
e. Tooling & Sub-Agents
- Tool definitions (src/tools/\*Tool)
- Agent orchestration (AGENTS.md, src/utils/agentLoader.ts, src/services/responseStateManager.ts)
f. Services & Adapters
- AI service adapters (OpenAI, Claude, custom…) under src/services/adapters
- OAuth, MCP server, notifier, cost-tracking, VCR (src/services/*)
g. UI / Rendering Layer
- React components for terminal UI (src/components/**)
- Hooks & context providers for interactive views (src/hooks, src/context/PermissionContext.tsx)
h. Persistence & Configuration
- File-based configs (~/.kode.json), agent storage, expert chat storage (src/utils/*Storage)
- Permission logs, cost history
i. Utils & Shared Libraries
- Fuzzy matchers, diffing, logging, file I/O, shell execution (src/utils/**)
- Common types (src/types)

##### Relationships & Data Flow
1. User launches CLI (cli.tsx) → passes raw args to Command Processor.
2. Command Processor selects Command Module → fetches/updates Context via Context Manager.
3. Command Module invokes Tools or direct model requests:
- Calls ModelManager to select appropriate adapter.
- Sends prompt or sub-agent orchestration request.
4. Service Adapters handle external API calls → returns AI responses.
5. ResponseStateManager & UI Components render output to terminal.
6. If file edits or shell commands are issued, Tools call into Shell Execution / File I/O Utils.
7. Persistence layer logs operations, updates state, cost tracking, and permission records.

##### Architectural Patterns & Principles
- Layered Architecture: Clear separation between CLI, command logic, services, tools, and persistence.
- Plugin/Modular Pattern: Each command and tool is a self-contained module registered at startup.
- Adapter Pattern: AI providers are abstracted behind a common interface.
- Event-Driven / Message-Based Flow: Context and state updates propagate through hooks and context providers.
- Configuration-Driven: Model profiles and pointers are entirely configurable and hot-swappable.

##### Essential Details to Capture
- Multi-model collaboration: show multiple adapters connected to ModelManager.
- Permission system: highlight permission requests flowing through PermissionContext → user approval → Tools.
- Cost tracking: illustrate /cost command querying CostTracker service.
- Docker integration: separate container boundary with mounted volumes and working directory.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Entrypoints
    subgraph "Entrypoints" 
        direction TB
        CLI["CLI Entrypoint"]:::appLayer
        MCP["MCP Entrypoint"]:::appLayer
        Docker["Docker Wrapper & Deployment Guide"]:::external
    end

    %% Command Processor Layer
    subgraph "Command Processor" 
        direction TB
        Registry["Command Registry"]:::appLayer
        Commands["Individual Command Modules"]:::appLayer
    end

    %% Context & State Manager
    subgraph "Context & State" 
        direction TB
        Context["Conversation/Context Manager"]:::appLayer
        MessageCtx["Message Context Manager"]:::appLayer
        History["Session State & History"]:::appLayer
    end

    %% Model Management
    subgraph "Model Management" 
        direction TB
        ModelMgr["ModelManager & Adapter Factory"]:::appLayer
        Configs["Model Configuration Constants"]:::infra
        subgraph "AI Adapters" 
            direction TB
            Adapters["Service Adapters"]:::infra
        end
    end

    %% Tools & Sub-Agents
    subgraph "Tools & Sub-Agents" 
        direction TB
        Tools["Tool Definitions & Plugins"]:::appLayer
        AgentLoader["Sub-Agent Orchestration"]:::appLayer
        AgentStore["Agent Storage"]:::infra
    end

    %% Services Layer
    subgraph "Services & Integrations" 
        direction TB
        OAuth["OAuth Integration Service"]:::infra
        MCPFlow["MCP Client & Server Approval Flow"]:::infra
        Notifier["Notifier Service"]:::infra
        VCR["VCR Service"]:::infra
        ResponseMgr["Response State Manager"]:::appLayer
    end

    %% UI Layer
    subgraph "UI / Rendering" 
        direction TB
        UI["Terminal UI Components"]:::ui
        Hooks["React Hooks & Permission Context"]:::ui
    end

    %% Persistence & Config
    subgraph "Persistence & Config" 
        direction TB
        ConfigsFS["File-based Config & Expert Chat Storage"]:::infra
        AgentStoreFS["Agent Storage Persistence"]:::infra
    end

    %% Utilities
    subgraph "Utils & Shared Libraries" 
        direction TB
        ShellFS["Shell Execution & File I/O"]:::infra
        Types["Common Type Definitions"]:::infra
    end

    %% External Systems
    subgraph "External Systems" 
        direction TB
        Shell["Shell & File System"]:::external
        Network["Network / AI Endpoints"]:::external
    end

    %% Connections
    CLI -->|executes| Registry
    MCP -->|executes| Registry
    Registry -->|routes to| Commands
    Commands -->|↔ update| Context
    Commands -->|↔ update| History
    Commands -->|invokes| ModelMgr
    ModelMgr -->|uses| Adapters
    ModelMgr -->|reads| Configs
    Commands -->|uses| Tools
    Tools -->|loads agents via| AgentLoader
    AgentLoader -->|persists| AgentStore
    Commands -->|logs to| ResponseMgr
    ResponseMgr -->|renders via| UI
    UI -->|hooks into| Hooks
    Hooks -->|requests permission| Tools
    Tools -->|executes shell I/O| ShellFS
    Commands -->|calls external| Network
    Adapters -->|calls API| Network
    OAuth -->|integrates with| Adapters
    MCPFlow -->|manages approval| Commands
    Notifier -->|notifies via| UI
    VCR -->|records/replays| Adapters
    Commands -->|reads/writes| ConfigsFS
    AgentLoader -->|reads/writes| AgentStoreFS
    ShellFS -->|interacts with| Shell

    %% Click Events
    click CLI "https://github.com/shareai-lab/kode/blob/main/src/entrypoints/cli.tsx"
    click MCP "https://github.com/shareai-lab/kode/blob/main/src/entrypoints/mcp.ts"
    click Docker "https://github.com/shareai-lab/kode/tree/main/Dockerfile"
    click Registry "https://github.com/shareai-lab/kode/blob/main/src/commands.ts"
    click Commands "https://github.com/shareai-lab/kode/tree/main/src/commands/*"
    click Context "https://github.com/shareai-lab/kode/blob/main/src/context.ts"
    click MessageCtx "https://github.com/shareai-lab/kode/blob/main/src/utils/messageContextManager.ts"
    click History "https://github.com/shareai-lab/kode/blob/main/src/history.ts"
    click History "https://github.com/shareai-lab/kode/blob/main/src/utils/sessionState.ts"
    click ModelMgr "https://github.com/shareai-lab/kode/blob/main/src/services/modelAdapterFactory.ts"
    click Adapters "https://github.com/shareai-lab/kode/tree/main/src/services/adapters/*"
    click Configs "https://github.com/shareai-lab/kode/blob/main/src/constants/models.ts"
    click Configs "https://github.com/shareai-lab/kode/blob/main/src/constants/modelCapabilities.ts"
    click Tools "https://github.com/shareai-lab/kode/tree/main/src/tools/*"
    click AgentLoader "https://github.com/shareai-lab/kode/blob/main/src/utils/agentLoader.ts"
    click AgentStore "https://github.com/shareai-lab/kode/blob/main/src/utils/agentStorage.ts"
    click ResponseMgr "https://github.com/shareai-lab/kode/blob/main/src/services/responseStateManager.ts"
    click OAuth "https://github.com/shareai-lab/kode/blob/main/src/services/oauth.ts"
    click MCPFlow "https://github.com/shareai-lab/kode/blob/main/src/services/mcpClient.ts"
    click MCPFlow "https://github.com/shareai-lab/kode/blob/main/src/services/mcpServerApproval.tsx"
    click Notifier "https://github.com/shareai-lab/kode/blob/main/src/services/notifier.ts"
    click VCR "https://github.com/shareai-lab/kode/blob/main/src/services/vcr.ts"
    click UI "https://github.com/shareai-lab/kode/tree/main/src/components/**"
    click Hooks "https://github.com/shareai-lab/kode/tree/main/src/hooks/**"
    click Hooks "https://github.com/shareai-lab/kode/blob/main/src/context/PermissionContext.tsx"
    click ConfigsFS "https://github.com/shareai-lab/kode/blob/main/src/utils/config.ts"
    click ConfigsFS "https://github.com/shareai-lab/kode/blob/main/src/utils/expertChatStorage.ts"
    click ShellFS "https://github.com/shareai-lab/kode/tree/main/src/utils/**"
    click Types "https://github.com/shareai-lab/kode/tree/main/src/types/**"

    %% Styles
    classDef appLayer fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef infra fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ui fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
