# pythagora-io/gpt-pilot architecture

> Architecture diagram of the GitHub repository pythagora-io/gpt-pilot, 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/pythagora-io/gpt-pilot
- Repository: https://github.com/pythagora-io/gpt-pilot

## Overview

GPT Pilot is an AI developer companion that builds applications through user-guided agent workflows. The CLI starts or resumes projects; an orchestrator coordinates specification and development agents, which use LLMs, project state, execution tools, and the UI to produce and refine workspace code. The README documents project listing and continuation; the tree also shows template, filesystem, and persistence subsystems. Some agent implementations and UI/API wiring were not sampled, so those links are omitted where evidence is insufficient.

Main entry points: [`core/agents/base.py`](https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/base.py) (Agent Base), [`core/agents/orchestrator.py`](https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/orchestrator.py) (Agent Orchestrator), [`core/state/state_manager.py`](https://github.com/pythagora-io/gpt-pilot/blob/main/core/state/state_manager.py) (Project State Manager), [`core/cli/main.py`](https://github.com/pythagora-io/gpt-pilot/blob/main/core/cli/main.py) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and Orchestration"]
  node_cli["CLI<br/>[main.py]"]
  node_orchestrator["Agent Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_agents["Development Agents"]
  node_spec["Specification Writer<br/>[spec_writer.py]"]
  node_developer_agent["Developer Agent<br/>[developer.py]"]
  node_bug_hunter["Bug Hunter<br/>[bug_hunter.py]"]
  node_agent_base["Agent Base<br/>[base.py]"]
end

subgraph group_runtime["LLM and Execution"]
  node_ui["User Interface<br/>[base.py]"]
  node_llm["LLM Client Layer<br/>[base.py]"]
  node_anthropic["Anthropic Client"]
  node_process["Process Manager<br/>[process_manager.py]"]
end

subgraph group_project["Project State"]
  node_state["Project State Manager<br/>[state_manager.py]"]
  node_state_model["Project State Model<br/>[project_state.py]"]
  node_database[("Project Database<br/>[session.py]")]
end

subgraph group_output["Workspace and Templates"]
  node_filesystem["Workspace Filesystem<br/>[vfs.py]"]
  node_templates["App Templates<br/>[registry.py]"]
end

node_user(("Developer"))
node_llm_provider(("LLM Provider"))

node_user -->|"starts or resumes"| node_cli
node_cli -->|"runs project"| node_orchestrator
node_orchestrator -->|"dispatches"| node_spec
node_orchestrator -->|"dispatches"| node_developer_agent
node_orchestrator -->|"dispatches"| node_bug_hunter
node_spec -->|"reads registry"| node_templates
node_agent_base -->|"sends prompts"| node_ui
node_agent_base -->|"uses state"| node_state
node_agent_base -->|"creates client"| node_llm
node_agent_base -->|"uses manager"| node_process
node_llm -->|"selects provider"| node_anthropic
node_anthropic -->|"sends requests"| node_llm_provider
node_state -->|"loads and saves"| node_state_model
node_state -->|"uses sessions"| node_database
node_state -->|"reads workspace"| node_filesystem

click node_cli "https://github.com/pythagora-io/gpt-pilot/blob/main/core/cli/main.py"
click node_orchestrator "https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/orchestrator.py"
click node_spec "https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/spec_writer.py"
click node_developer_agent "https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/developer.py"
click node_bug_hunter "https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/bug_hunter.py"
click node_agent_base "https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/base.py"
click node_ui "https://github.com/pythagora-io/gpt-pilot/blob/main/core/ui/base.py"
click node_llm "https://github.com/pythagora-io/gpt-pilot/blob/main/core/llm/base.py"
click node_anthropic "https://github.com/pythagora-io/gpt-pilot/blob/main/core/llm/anthropic_client.py"
click node_process "https://github.com/pythagora-io/gpt-pilot/blob/main/core/proc/process_manager.py"
click node_state "https://github.com/pythagora-io/gpt-pilot/blob/main/core/state/state_manager.py"
click node_state_model "https://github.com/pythagora-io/gpt-pilot/blob/main/core/db/models/project_state.py"
click node_database "https://github.com/pythagora-io/gpt-pilot/blob/main/core/db/session.py"
click node_filesystem "https://github.com/pythagora-io/gpt-pilot/blob/main/core/disk/vfs.py"
click node_templates "https://github.com/pythagora-io/gpt-pilot/blob/main/core/templates/registry.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_cli,node_orchestrator toneBlue
class node_spec,node_developer_agent,node_bug_hunter,node_agent_base toneAmber
class node_ui,node_llm,node_anthropic,node_process toneMint
class node_state,node_state_model,node_database toneRose
class node_filesystem,node_templates,node_user,node_llm_provider toneIndigo
```

## Components

### CLI and Orchestration

- [CLI](https://github.com/pythagora-io/gpt-pilot/blob/main/core/cli/main.py): `core/cli/main.py`
- [Agent Orchestrator](https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/orchestrator.py): `core/agents/orchestrator.py`

### Development Agents

- [Specification Writer](https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/spec_writer.py): `core/agents/spec_writer.py`
- [Developer Agent](https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/developer.py): `core/agents/developer.py`
- [Bug Hunter](https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/bug_hunter.py): `core/agents/bug_hunter.py`
- [Agent Base](https://github.com/pythagora-io/gpt-pilot/blob/main/core/agents/base.py): `core/agents/base.py`

### LLM and Execution

- [User Interface](https://github.com/pythagora-io/gpt-pilot/blob/main/core/ui/base.py): `core/ui/base.py`
- [LLM Client Layer](https://github.com/pythagora-io/gpt-pilot/blob/main/core/llm/base.py): `core/llm/base.py`
- [Anthropic Client](https://github.com/pythagora-io/gpt-pilot/blob/main/core/llm/anthropic_client.py): `core/llm/anthropic_client.py`
- [Process Manager](https://github.com/pythagora-io/gpt-pilot/blob/main/core/proc/process_manager.py): `core/proc/process_manager.py`

### Project State

- [Project State Manager](https://github.com/pythagora-io/gpt-pilot/blob/main/core/state/state_manager.py): `core/state/state_manager.py`
- [Project State Model](https://github.com/pythagora-io/gpt-pilot/blob/main/core/db/models/project_state.py): `core/db/models/project_state.py`
- [Project Database](https://github.com/pythagora-io/gpt-pilot/blob/main/core/db/session.py): `core/db/session.py`

### Workspace and Templates

- [Workspace Filesystem](https://github.com/pythagora-io/gpt-pilot/blob/main/core/disk/vfs.py): `core/disk/vfs.py`
- [App Templates](https://github.com/pythagora-io/gpt-pilot/blob/main/core/templates/registry.py): `core/templates/registry.py`

### Other components

- **Developer**
- **LLM Provider**

## Connections

- Developer → CLI: starts or resumes (evidence: `README.md`)
- CLI → Agent Orchestrator: runs project (evidence: `core/cli/main.py`)
- Agent Orchestrator → Specification Writer: dispatches (evidence: `core/agents/orchestrator.py`)
- Agent Orchestrator → Developer Agent: dispatches (evidence: `core/agents/orchestrator.py`)
- Agent Orchestrator → Bug Hunter: dispatches (evidence: `core/agents/orchestrator.py`)
- Specification Writer → App Templates: reads registry (evidence: `core/agents/spec_writer.py`)
- Agent Base → User Interface: sends prompts (evidence: `core/agents/base.py`)
- Agent Base → Project State Manager: uses state (evidence: `core/agents/base.py`)
- Agent Base → LLM Client Layer: creates client (evidence: `core/agents/base.py`)
- Agent Base → Process Manager: uses manager (evidence: `core/agents/base.py`)
- LLM Client Layer → Anthropic Client: selects provider (evidence: `core/llm/base.py`)
- Anthropic Client → LLM Provider: sends requests (evidence: `core/llm/anthropic_client.py`)
- Project State Manager → Project State Model: loads and saves (evidence: `core/state/state_manager.py`)
- Project State Manager → Project Database: uses sessions (evidence: `core/state/state_manager.py`)
- Project State Manager → Workspace Filesystem: reads workspace (evidence: `core/state/state_manager.py`)
