# vinyluis/claude-code-supervisor architecture

> Architecture diagram of the GitHub repository vinyluis/claude-code-supervisor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vinyluis/claude-code-supervisor
- Repository: https://github.com/vinyluis/claude-code-supervisor

## Overview

Claude Code Supervisor is a Python wrapper that coordinates a coding agent and a supervisor LLM to solve programming tasks. Users submit a problem through the public agent API; optional plan review precedes coding, then the supervisor monitors results and either returns a completion or supplies feedback for another iteration. The README documents data I/O, custom prompts and tools, automated tests, and Anthropic, Bedrock, and OpenAI support. Internal details are based on sampled excerpts and the source index; unsampled implementation links are omitted where their ownership is unclear.

Main entry points: [`claude_code_supervisor/supervisor.py`](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py) (Workflow Engine), [`claude_code_supervisor/__init__.py`](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/__init__.py) (Supervisor API), [`claude_code_supervisor/config.py`](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/config.py) (Agent Configuration), [`claude_code_supervisor/__version__.py`](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/__version__.py) (Package Metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_public_api["Supervisor API<br/>[__init__.py]"]
  node_version["Package Metadata<br/>[__version__.py]"]
end

subgraph group_orchestration["Workflow Orchestration"]
  node_workflow["Workflow Engine<br/>[supervisor.py]"]
  node_execution["Execution Session<br/>[supervisor.py]"]
  node_monitoring["Progress Monitoring<br/>[supervisor.py]"]
  node_validation["Test Analysis<br/>[supervisor.py]"]
  node_feedback["Feedback Loop<br/>[supervisor.py]"]
end

subgraph group_planning["Plan Review"]
  node_plan_mode["Plan Mode<br/>[supervisor.py]"]
  node_plan_review["Plan Review<br/>[supervisor.py]"]
end

subgraph group_support["Configuration and Support"]
  node_config["Agent Configuration<br/>[config.py]"]
  node_prompt_templates["Prompt Templates<br/>[prompts.py]"]
  node_utilities["Output Utilities<br/>[utils.py]"]
end

subgraph group_agents["Agent Integrations"]
  node_coding_agent["Claude Code"]
  node_guidance_llm["Guidance LLM"]
  node_custom_tools["Custom Tools"]
  node_provider_services["Model Providers"]
end

node_developer(("Developer"))

node_developer -->|"submits problem"| node_public_api
node_public_api -->|"invokes agent"| node_workflow
node_workflow -->|"loads settings"| node_config
node_workflow -->|"builds instructions"| node_prompt_templates
node_workflow -->|"formats progress"| node_utilities
node_workflow -->|"starts optional plan"| node_plan_mode
node_plan_mode -->|"requests plan"| node_coding_agent
node_plan_mode -->|"reviews plan"| node_plan_review
node_plan_review -.->|"scores plan"| node_guidance_llm
node_plan_review -.->|"approves plan"| node_execution
node_workflow -->|"runs execution"| node_execution
node_execution -->|"runs coding session"| node_coding_agent
node_coding_agent -->|"reports progress"| node_monitoring
node_monitoring -.->|"provides results"| node_validation
node_validation -->|"runs tests"| node_coding_agent
node_validation -.->|"reports issues"| node_feedback
node_feedback -->|"requests guidance"| node_guidance_llm
node_feedback -->|"sends feedback"| node_coding_agent
node_config -.->|"selects provider"| node_provider_services
node_config -.->|"configures tools"| node_custom_tools
node_workflow -.->|"uses model"| node_provider_services
node_public_api -->|"exports version"| node_version

click node_public_api "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/__init__.py"
click node_workflow "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py"
click node_execution "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py"
click node_monitoring "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py"
click node_validation "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py"
click node_feedback "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py"
click node_plan_mode "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py"
click node_plan_review "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py"
click node_config "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/config.py"
click node_prompt_templates "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/prompts.py"
click node_utilities "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/utils.py"
click node_version "https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/__version__.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_public_api,node_version toneBlue
class node_workflow,node_execution,node_monitoring,node_validation,node_feedback toneAmber
class node_plan_mode,node_plan_review toneMint
class node_config,node_prompt_templates,node_utilities toneRose
class node_coding_agent,node_guidance_llm,node_custom_tools,node_provider_services,node_developer toneIndigo
```

## Components

### Public API

- [Supervisor API](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/__init__.py): `claude_code_supervisor/__init__.py`
- [Package Metadata](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/__version__.py): `claude_code_supervisor/__version__.py`

### Workflow Orchestration

- [Workflow Engine](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py): `claude_code_supervisor/supervisor.py`
- [Execution Session](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py): `claude_code_supervisor/supervisor.py`
- [Progress Monitoring](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py): `claude_code_supervisor/supervisor.py`
- [Test Analysis](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py): `claude_code_supervisor/supervisor.py`
- [Feedback Loop](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py): `claude_code_supervisor/supervisor.py`

### Plan Review

- [Plan Mode](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py): `claude_code_supervisor/supervisor.py`
- [Plan Review](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/supervisor.py): `claude_code_supervisor/supervisor.py`

### Configuration and Support

- [Agent Configuration](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/config.py): `claude_code_supervisor/config.py`
- [Prompt Templates](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/prompts.py): `claude_code_supervisor/prompts.py`
- [Output Utilities](https://github.com/vinyluis/claude-code-supervisor/blob/main/claude_code_supervisor/utils.py): `claude_code_supervisor/utils.py`

### Agent Integrations

- **Claude Code**
- **Guidance LLM**
- **Custom Tools**
- **Model Providers**

### Other components

- **Developer**

## Connections

- Developer → Supervisor API: submits problem (evidence: `README.md`)
- Supervisor API → Workflow Engine: invokes agent (evidence: `claude_code_supervisor/__init__.py`)
- Workflow Engine → Agent Configuration: loads settings (evidence: `claude_code_supervisor/supervisor.py`)
- Workflow Engine → Prompt Templates: builds instructions (evidence: `claude_code_supervisor/supervisor.py`)
- Workflow Engine → Output Utilities: formats progress (evidence: `claude_code_supervisor/supervisor.py`)
- Workflow Engine → Plan Mode: starts optional plan (evidence: `claude_code_supervisor/supervisor.py`)
- Plan Mode → Claude Code: requests plan (evidence: `README.md`)
- Plan Mode → Plan Review: reviews plan (evidence: `claude_code_supervisor/supervisor.py`)
- Plan Review → Guidance LLM: scores plan
- Plan Review → Execution Session: approves plan (evidence: `claude_code_supervisor/supervisor.py`)
- Workflow Engine → Execution Session: runs execution (evidence: `claude_code_supervisor/supervisor.py`)
- Execution Session → Claude Code: runs coding session (evidence: `README.md`)
- Claude Code → Progress Monitoring: reports progress (evidence: `README.md`)
- Progress Monitoring → Test Analysis: provides results (evidence: `claude_code_supervisor/supervisor.py`)
- Test Analysis → Claude Code: runs tests (evidence: `README.md`)
- Test Analysis → Feedback Loop: reports issues (evidence: `claude_code_supervisor/supervisor.py`)
- Feedback Loop → Guidance LLM: requests guidance (evidence: `README.md`)
- Feedback Loop → Claude Code: sends feedback (evidence: `README.md`)
- Agent Configuration → Model Providers: selects provider
- Agent Configuration → Custom Tools: configures tools
- Workflow Engine → Model Providers: uses model
- Supervisor API → Package Metadata: exports version (evidence: `claude_code_supervisor/__init__.py`)