# app0lyon/mycodex architecture

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

- Interactive diagram: https://gitdiagram.com/app0lyon/mycodex
- Repository: https://github.com/app0lyon/mycodex

## Overview

MyCodex is a local coding copilot: a user submits a goal through the VS Code chat or backend API/CLI; the agent gathers workspace context, plans and executes tasks, reviews and corrects results, then returns a response. The repository also documents prompt-only optimization, session memory, local search, and an optional NVIDIA provider. The agent’s orchestrator coordinates the workflow; the VS Code extension provides the chat and transport. Some connections are supported by the SOURCE INDEX or README rather than complete source excerpts.

Main entry points: [`agent/orchestrator.py`](https://github.com/app0lyon/mycodex/blob/main/agent/orchestrator.py) (Workflow orchestrator), [`agent/clients/ollama_client.py`](https://github.com/app0lyon/mycodex/blob/main/agent/clients/ollama_client.py) (Ollama client), [`agent/agents/executor.py`](https://github.com/app0lyon/mycodex/blob/main/agent/agents/executor.py) (Code executor), [`agent/agents/reviewer.py`](https://github.com/app0lyon/mycodex/blob/main/agent/agents/reviewer.py) (Task reviewer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vscode["VS Code chat"]
  node_extension["Extension commands<br/>[extension.ts]"]
  node_panel["Chat panel<br/>[panel.ts]"]
  node_webview["Chat interface<br/>[html.ts]"]
  node_messaging["Webview messaging<br/>[messaging.ts]"]
  node_backend["Request transport<br/>[backend.ts]"]
  node_workspace_ext["Workspace utilities<br/>[workspace.ts]"]
end

subgraph group_entry["Agent entry"]
  node_main["API and CLI<br/>[main.py]"]
end

subgraph group_workflow["Task workflow"]
  node_orchestrator["Workflow orchestrator<br/>[orchestrator.py]"]
  node_optimizer["Prompt optimizer"]
  node_planner["Task planner<br/>[planner.py]"]
  node_tasks["Task models<br/>[tasks.py]"]
  node_executor["Code executor<br/>[executor.py]"]
  node_reviewer["Task reviewer<br/>[reviewer.py]"]
  node_critic["Final critic<br/>[critic.py]"]
  node_correction["Self correction<br/>[self_correction.py]"]
  node_responder["Final responder<br/>[responder.py]"]
end

subgraph group_support["Context and state"]
  node_searcher["Workspace search<br/>[searcher.py]"]
  node_workspace_context["Workspace context"]
  node_patcher["Workspace patching"]
  node_memory[("Session memory<br/>[memory.py]")]
  node_prompts["Prompt templates"]
  node_renderer["Prompt renderer<br/>[prompt_renderer.py]"]
  node_costs[("Cost logging<br/>[cost_logger.py]")]
end

subgraph group_providers["Models and services"]
  node_ollama_client["Ollama client<br/>[ollama_client.py]"]
  node_nvidia_client["NVIDIA client"]
  node_search_client["Search client<br/>[search_client.py]"]
  node_ollama(("Ollama service"))
  node_nvidia(("NVIDIA Build"))
  node_duckduckgo(("DuckDuckGo API"))
end

node_user(("User"))

node_user -->|"opens chat"| node_extension
node_extension -->|"opens panel"| node_panel
node_panel -->|"renders"| node_webview
node_panel -->|"uses"| node_messaging
node_messaging -->|"sends requests"| node_backend
node_messaging -->|"reads workspace"| node_workspace_ext
node_backend -->|"calls API or CLI"| node_main
node_user -->|"submits goal"| node_main
node_main -->|"runs workflow"| node_orchestrator
node_main -->|"configures memory"| node_memory
node_orchestrator -->|"optimizes prompt"| node_optimizer
node_orchestrator -->|"plans tasks"| node_planner
node_orchestrator -->|"executes tasks"| node_executor
node_orchestrator -->|"reviews tasks"| node_reviewer
node_orchestrator -->|"evaluates results"| node_critic
node_orchestrator -->|"corrects results"| node_correction
node_orchestrator -->|"builds response"| node_responder
node_orchestrator -->|"searches workspace"| node_searcher
node_orchestrator -->|"gathers context"| node_workspace_context
node_orchestrator -->|"applies edits"| node_patcher
node_orchestrator -->|"uses session memory"| node_memory
node_planner -.->|"creates tasks"| node_tasks
node_executor -->|"parses output"| node_tasks
node_reviewer -->|"parses review"| node_tasks
node_executor -->|"requests completion"| node_ollama_client
node_reviewer -->|"requests review"| node_ollama_client
node_planner -->|"requests plan"| node_ollama_client
node_optimizer -->|"requests rewrite"| node_ollama_client
node_responder -->|"requests response"| node_ollama_client
node_critic -->|"requests critique"| node_ollama_client
node_correction -->|"requests correction"| node_ollama_client
node_searcher -->|"searches web"| node_search_client
node_executor -->|"renders prompt"| node_renderer
node_reviewer -->|"renders prompt"| node_renderer
node_executor -->|"uses templates"| node_prompts
node_reviewer -->|"uses templates"| node_prompts
node_ollama_client -->|"sends chat"| node_ollama
node_nvidia_client -->|"sends chat"| node_nvidia
node_orchestrator -.->|"selects provider"| node_nvidia_client
node_search_client -->|"queries"| node_duckduckgo
node_ollama_client -->|"logs usage"| node_costs
node_nvidia_client -->|"logs usage"| node_costs

click node_extension "https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/extension.ts"
click node_panel "https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/panel.ts"
click node_webview "https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/webview/html.ts"
click node_messaging "https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/webview/messaging.ts"
click node_backend "https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/backend.ts"
click node_workspace_ext "https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/utils/workspace.ts"
click node_main "https://github.com/app0lyon/mycodex/blob/main/agent/main.py"
click node_orchestrator "https://github.com/app0lyon/mycodex/blob/main/agent/orchestrator.py"
click node_optimizer "https://github.com/app0lyon/mycodex/blob/main/agent/agents/prompt_optimizer.py"
click node_planner "https://github.com/app0lyon/mycodex/blob/main/agent/agents/planner.py"
click node_tasks "https://github.com/app0lyon/mycodex/blob/main/agent/models/tasks.py"
click node_executor "https://github.com/app0lyon/mycodex/blob/main/agent/agents/executor.py"
click node_reviewer "https://github.com/app0lyon/mycodex/blob/main/agent/agents/reviewer.py"
click node_critic "https://github.com/app0lyon/mycodex/blob/main/agent/agents/critic.py"
click node_correction "https://github.com/app0lyon/mycodex/blob/main/agent/agents/self_correction.py"
click node_responder "https://github.com/app0lyon/mycodex/blob/main/agent/agents/responder.py"
click node_searcher "https://github.com/app0lyon/mycodex/blob/main/agent/agents/searcher.py"
click node_workspace_context "https://github.com/app0lyon/mycodex/blob/main/agent/utils/workspace_context.py"
click node_patcher "https://github.com/app0lyon/mycodex/blob/main/agent/utils/workspace_patcher.py"
click node_memory "https://github.com/app0lyon/mycodex/blob/main/agent/utils/memory.py"
click node_prompts "https://github.com/app0lyon/mycodex/tree/main/agent/prompts"
click node_renderer "https://github.com/app0lyon/mycodex/blob/main/agent/utils/prompt_renderer.py"
click node_costs "https://github.com/app0lyon/mycodex/blob/main/agent/utils/cost_logger.py"
click node_ollama_client "https://github.com/app0lyon/mycodex/blob/main/agent/clients/ollama_client.py"
click node_nvidia_client "https://github.com/app0lyon/mycodex/blob/main/agent/clients/nvidia_build_client.py"
click node_search_client "https://github.com/app0lyon/mycodex/blob/main/agent/clients/search_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extension,node_panel,node_webview,node_messaging,node_backend,node_workspace_ext,node_user toneBlue
class node_main toneAmber
class node_orchestrator,node_optimizer,node_planner,node_tasks,node_executor,node_reviewer,node_critic,node_correction,node_responder toneMint
class node_searcher,node_workspace_context,node_patcher,node_memory,node_prompts,node_renderer,node_costs toneRose
class node_ollama_client,node_nvidia_client,node_search_client,node_ollama,node_nvidia,node_duckduckgo toneIndigo
```

## Components

### VS Code chat

- [Extension commands](https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/extension.ts): `vscode-extension/mycodex/src/extension.ts`
- [Chat panel](https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/panel.ts): `vscode-extension/mycodex/src/panel.ts`
- [Chat interface](https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/webview/html.ts): `vscode-extension/mycodex/src/webview/html.ts`
- [Webview messaging](https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/webview/messaging.ts): `vscode-extension/mycodex/src/webview/messaging.ts`
- [Request transport](https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/backend.ts): `vscode-extension/mycodex/src/backend.ts`
- [Workspace utilities](https://github.com/app0lyon/mycodex/blob/main/vscode-extension/mycodex/src/utils/workspace.ts): `vscode-extension/mycodex/src/utils/workspace.ts`

### Agent entry

- [API and CLI](https://github.com/app0lyon/mycodex/blob/main/agent/main.py): `agent/main.py`

### Task workflow

- [Workflow orchestrator](https://github.com/app0lyon/mycodex/blob/main/agent/orchestrator.py): `agent/orchestrator.py`
- [Prompt optimizer](https://github.com/app0lyon/mycodex/blob/main/agent/agents/prompt_optimizer.py): `agent/agents/prompt_optimizer.py`
- [Task planner](https://github.com/app0lyon/mycodex/blob/main/agent/agents/planner.py): `agent/agents/planner.py`
- [Task models](https://github.com/app0lyon/mycodex/blob/main/agent/models/tasks.py): `agent/models/tasks.py`
- [Code executor](https://github.com/app0lyon/mycodex/blob/main/agent/agents/executor.py): `agent/agents/executor.py`
- [Task reviewer](https://github.com/app0lyon/mycodex/blob/main/agent/agents/reviewer.py): `agent/agents/reviewer.py`
- [Final critic](https://github.com/app0lyon/mycodex/blob/main/agent/agents/critic.py): `agent/agents/critic.py`
- [Self correction](https://github.com/app0lyon/mycodex/blob/main/agent/agents/self_correction.py): `agent/agents/self_correction.py`
- [Final responder](https://github.com/app0lyon/mycodex/blob/main/agent/agents/responder.py): `agent/agents/responder.py`

### Context and state

- [Workspace search](https://github.com/app0lyon/mycodex/blob/main/agent/agents/searcher.py): `agent/agents/searcher.py`
- [Workspace context](https://github.com/app0lyon/mycodex/blob/main/agent/utils/workspace_context.py): `agent/utils/workspace_context.py`
- [Workspace patching](https://github.com/app0lyon/mycodex/blob/main/agent/utils/workspace_patcher.py): `agent/utils/workspace_patcher.py`
- [Session memory](https://github.com/app0lyon/mycodex/blob/main/agent/utils/memory.py): `agent/utils/memory.py`
- [Prompt templates](https://github.com/app0lyon/mycodex/tree/main/agent/prompts): `agent/prompts`
- [Prompt renderer](https://github.com/app0lyon/mycodex/blob/main/agent/utils/prompt_renderer.py): `agent/utils/prompt_renderer.py`
- [Cost logging](https://github.com/app0lyon/mycodex/blob/main/agent/utils/cost_logger.py): `agent/utils/cost_logger.py`

### Models and services

- [Ollama client](https://github.com/app0lyon/mycodex/blob/main/agent/clients/ollama_client.py): `agent/clients/ollama_client.py`
- [NVIDIA client](https://github.com/app0lyon/mycodex/blob/main/agent/clients/nvidia_build_client.py): `agent/clients/nvidia_build_client.py`
- [Search client](https://github.com/app0lyon/mycodex/blob/main/agent/clients/search_client.py): `agent/clients/search_client.py`
- **Ollama service**
- **NVIDIA Build**
- **DuckDuckGo API**

### Other components

- **User**

## Connections

- User → Extension commands: opens chat (evidence: `README.md`)
- Extension commands → Chat panel: opens panel (evidence: `vscode-extension/mycodex/src/extension.ts`)
- Chat panel → Chat interface: renders (evidence: `vscode-extension/mycodex/src/panel.ts`)
- Chat panel → Webview messaging: uses (evidence: `vscode-extension/mycodex/src/panel.ts`)
- Webview messaging → Request transport: sends requests (evidence: `vscode-extension/mycodex/src/webview/messaging.ts`)
- Webview messaging → Workspace utilities: reads workspace (evidence: `vscode-extension/mycodex/src/webview/messaging.ts`)
- Request transport → API and CLI: calls API or CLI (evidence: `README.md`)
- User → API and CLI: submits goal (evidence: `README.md`)
- API and CLI → Workflow orchestrator: runs workflow (evidence: `agent/main.py`)
- API and CLI → Session memory: configures memory (evidence: `agent/main.py`)
- Workflow orchestrator → Prompt optimizer: optimizes prompt (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Task planner: plans tasks (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Code executor: executes tasks (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Task reviewer: reviews tasks (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Final critic: evaluates results (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Self correction: corrects results (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Final responder: builds response (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Workspace search: searches workspace (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Workspace context: gathers context (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Workspace patching: applies edits (evidence: `agent/orchestrator.py`)
- Workflow orchestrator → Session memory: uses session memory (evidence: `agent/orchestrator.py`)
- Task planner → Task models: creates tasks (evidence: `agent/agents/planner.py`)
- Code executor → Task models: parses output (evidence: `agent/agents/executor.py`)
- Task reviewer → Task models: parses review (evidence: `agent/agents/reviewer.py`)
- Code executor → Ollama client: requests completion (evidence: `agent/agents/executor.py`)
- Task reviewer → Ollama client: requests review (evidence: `agent/agents/reviewer.py`)
- Task planner → Ollama client: requests plan (evidence: `agent/agents/planner.py`)
- Prompt optimizer → Ollama client: requests rewrite (evidence: `agent/agents/prompt_optimizer.py`)
- Final responder → Ollama client: requests response (evidence: `agent/agents/responder.py`)
- Final critic → Ollama client: requests critique (evidence: `agent/agents/critic.py`)
- Self correction → Ollama client: requests correction (evidence: `agent/agents/self_correction.py`)
- Workspace search → Search client: searches web (evidence: `agent/agents/searcher.py`)
- Code executor → Prompt renderer: renders prompt (evidence: `agent/agents/executor.py`)
- Task reviewer → Prompt renderer: renders prompt (evidence: `agent/agents/reviewer.py`)
- Code executor → Prompt templates: uses templates (evidence: `agent/agents/executor.py`)
- Task reviewer → Prompt templates: uses templates (evidence: `agent/agents/reviewer.py`)
- Ollama client → Ollama service: sends chat (evidence: `agent/clients/ollama_client.py`)
- NVIDIA client → NVIDIA Build: sends chat (evidence: `agent/clients/nvidia_build_client.py`)
- Workflow orchestrator → NVIDIA client: selects provider (evidence: `agent/orchestrator.py`)
- Search client → DuckDuckGo API: queries (evidence: `agent/clients/search_client.py`)
- Ollama client → Cost logging: logs usage (evidence: `agent/clients/ollama_client.py`)
- NVIDIA client → Cost logging: logs usage (evidence: `agent/clients/nvidia_build_client.py`)
