# gpt-engineer-org/gpt-engineer architecture

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

- Interactive diagram: https://gitdiagram.com/gpt-engineer-org/gpt-engineer
- Repository: https://github.com/gpt-engineer-org/gpt-engineer

## Overview

#### Purpose and execution surfaces
gpt-engineer is a Python coding-agent experimentation platform: it turns a natural-language project `prompt` into generated code, can improve an existing codebase, execute generated code, and benchmark agent implementations. Primary installed entry points are the interactive project CLI and benchmark CLI, implemented in `gpt_engineer/applications/cli/main.py` and `gpt_engineer/benchmark/__main__.py`; package/runtime metadata is in `pyproject.toml`.

#### CLI application orchestration
The CLI accepts a project directory, model/options, and create-versus-improve mode. It collects prompt/image context, selects project files for improvement, configures an agent, and coordinates user-facing interaction and learning/telemetry behavior.
- `gpt_engineer/applications/cli/main.py`
- `gpt_engineer/applications/cli/cli_agent.py`
- `gpt_engineer/applications/cli/collect.py`

The project directory is the principal boundary: input prompt and source tree are read from it, while generated/modified files and execution effects are written there.

#### Agent abstractions and model boundary
Core interfaces separate agent behavior, AI/model calls, memory, and execution environment. The default simple agent composes these contracts, allowing alternative models or custom agent steps without changing the CLI workflow.
- `gpt_engineer/core/base_agent.py`
- `gpt_engineer/core/ai.py`
- `gpt_engineer/core/default/simple_agent.py`

Model access supports OpenAI by default and documented Azure OpenAI, Anthropic, and local/open-model alternatives. Credentials are supplied through environment variables or `.env`; no hosted application backend is implied.

#### Generation and improvement pipeline
Default staged workflows turn prompt/context into planning, code generation, execution, and corrective iterations. Improvement mode uses the existing repository as context and applies edits/diffs rather than creating solely from specification. Prompt-to-file parsing and diff handling are explicit boundaries between model text and filesystem mutations.
- `gpt_engineer/core/default/steps.py`
- `gpt_engineer/core/chat_to_files.py`
- `gpt_engineer/core/diff.py`

Preprompt assets establish the agent’s role and output conventions for clarification, generation, improvement, and file formats; projects may override them through CLI configuration.
- `gpt_engineer/preprompts/generate`
- `gpt_engineer/preprompts/improve`
- `gpt_engineer/core/preprompts_holder.py`

#### Filesystem, execution, and project state
Default disk-backed implementations persist conversational memory and generated files, execute commands in the target project, and manage paths/configuration. This is the high-risk boundary: AI-produced code is materialized and run locally.
- `gpt_engineer/core/default/disk_execution_env.py`
- `gpt_engineer/core/default/disk_memory.py`
- `gpt_engineer/core/default/file_store.py`

Git integration, linting, version tracking, token usage, and project config support reproducibility, validation, and operational accounting around the main loop.
- `gpt_engineer/core/git.py`
- `gpt_engineer/core/linting.py`
- `gpt_engineer/core/project_config.py`

#### Benchmark subsystem
A separate `bench` workflow loads benchmark problems, agent configurations, and dataset adapters, then runs agents against APPS and MBPP tasks. It is architecturally independent of interactive CLI generation but reuses agent-oriented concepts.
- `gpt_engineer/benchmark/run.py`
- `gpt_engineer/benchmark/bench_config.py`
- `gpt_engineer/benchmark/benchmarks/load.py`

#### Runtime and delivery
Supported runtime is Python 3.10–3.12. Development uses Poetry/package metadata; Docker provides an alternate isolated runtime and `docker-compose.yml` provides container orchestration. Documentation includes open-model integrations and tracing guidance.
- `docker/Dockerfile`
- `docker/entrypoint.sh`
- `docker-compose.yml`

Main entry points: [`gpt_engineer/core/default/simple_agent.py`](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/simple_agent.py) (Default simple agent), [`gpt_engineer/core/default/steps.py`](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/steps.py) (Generation and improvement steps), [`gpt_engineer/benchmark/run.py`](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/benchmark/run.py) (Benchmark runner), [`gpt_engineer/applications/cli/main.py`](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/applications/cli/main.py) (Project CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Interactive CLI"]
  node_cli_main["Project CLI<br/>CLI entry point<br/>[main.py]"]
  node_cli_agent["CLI agent orchestration<br/>workflow coordinator<br/>[cli_agent.py]"]
  node_context_collection["Prompt and context collection<br/>input collector<br/>[collect.py]"]
end

subgraph group_core["Agent Runtime"]
  node_agent_contract["Agent contracts<br/>core interfaces<br/>[base_agent.py]"]
  node_ai_boundary{{"Model providers<br/>AI abstraction<br/>[ai.py]"}}
  node_simple_agent["Default simple agent<br/>agent implementation<br/>[simple_agent.py]"]
  node_staged_steps["Generation and improvement steps<br/>pipeline<br/>[steps.py]"]
  node_preprompts["Preprompt assets<br/>prompt templates"]
  node_preprompt_loader["Preprompt loader<br/>configuration layer"]
  node_file_parser["Chat-to-files parser<br/>model text boundary<br/>[chat_to_files.py]"]
  node_diff_handler["Diff handler<br/>edit application<br/>[diff.py]"]
  node_disk_state[("Disk memory and file store<br/>persistent state<br/>[file_store.py]")]
  node_execution_env{{"Local execution environment<br/>command runner"}}
  node_project_ops["Project operations<br/>validation and tracking<br/>[project_config.py]"]
end

subgraph group_benchmark["Benchmarking"]
  node_bench_cli["Benchmark CLI<br/>CLI entry point<br/>[__main__.py]"]
  node_bench_runner["Benchmark runner<br/>evaluation workflow<br/>[run.py]"]
  node_benchmark_loader[("Benchmark datasets<br/>dataset adapters<br/>[load.py]")]
end

subgraph group_delivery["Delivery Runtime"]
  node_package_runtime["Python package runtime<br/>package metadata<br/>[pyproject.toml]"]
  node_docker_runtime["Container runtime<br/>isolated runtime"]
end

node_project[("Target project directory<br/>filesystem boundary")]

node_cli_main -->|"starts"| node_cli_agent
node_cli_main -->|"collects input"| node_context_collection
node_context_collection -->|"reads prompt and source tree"| node_project
node_cli_agent -->|"configures"| node_simple_agent
node_simple_agent -->|"implements"| node_agent_contract
node_simple_agent -->|"requests model output"| node_ai_boundary
node_simple_agent -->|"runs"| node_staged_steps
node_preprompt_loader -->|"loads"| node_preprompts
node_staged_steps -->|"uses conventions"| node_preprompt_loader
node_staged_steps -->|"parses generated output"| node_file_parser
node_file_parser -->|"writes generated files"| node_disk_state
node_diff_handler -->|"applies edits"| node_disk_state
node_disk_state -->|"materializes changes"| node_project
node_staged_steps -->|"executes and corrects"| node_execution_env
node_execution_env -->|"runs commands in"| node_project
node_project_ops -->|"tracks and validates"| node_project
node_bench_cli -->|"starts"| node_bench_runner
node_bench_runner -->|"loads tasks"| node_benchmark_loader
node_bench_runner -.->|"evaluates agents through"| node_agent_contract
node_package_runtime -->|"installs command"| node_cli_main
node_package_runtime -->|"installs command"| node_bench_cli
node_docker_runtime -->|"packages runtime"| node_package_runtime

click node_cli_main "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/applications/cli/main.py"
click node_cli_agent "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/applications/cli/cli_agent.py"
click node_context_collection "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/applications/cli/collect.py"
click node_agent_contract "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/base_agent.py"
click node_ai_boundary "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/ai.py"
click node_simple_agent "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/simple_agent.py"
click node_staged_steps "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/steps.py"
click node_preprompts "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/preprompts/generate"
click node_preprompt_loader "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/preprompts_holder.py"
click node_file_parser "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/chat_to_files.py"
click node_diff_handler "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/diff.py"
click node_disk_state "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/file_store.py"
click node_execution_env "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/disk_execution_env.py"
click node_project_ops "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/project_config.py"
click node_bench_cli "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/benchmark/__main__.py"
click node_bench_runner "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/benchmark/run.py"
click node_benchmark_loader "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/benchmark/benchmarks/load.py"
click node_package_runtime "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/pyproject.toml"
click node_docker_runtime "https://github.com/gpt-engineer-org/gpt-engineer/blob/main/docker/Dockerfile"

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_main,node_cli_agent,node_context_collection toneBlue
class node_agent_contract,node_ai_boundary,node_simple_agent,node_staged_steps,node_preprompts,node_preprompt_loader,node_file_parser,node_diff_handler,node_disk_state,node_execution_env,node_project_ops toneAmber
class node_bench_cli,node_bench_runner,node_benchmark_loader toneMint
class node_package_runtime,node_docker_runtime toneRose
class node_project toneNeutral
```

## Components

### Interactive CLI

- [Project CLI](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/applications/cli/main.py): CLI entry point · `gpt_engineer/applications/cli/main.py`
- [CLI agent orchestration](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/applications/cli/cli_agent.py): workflow coordinator · `gpt_engineer/applications/cli/cli_agent.py`
- [Prompt and context collection](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/applications/cli/collect.py): input collector · `gpt_engineer/applications/cli/collect.py`

### Agent Runtime

- [Agent contracts](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/base_agent.py): core interfaces · Separates agent behavior, model calls, memory, and execution. · `gpt_engineer/core/base_agent.py`
- [Model providers](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/ai.py): AI abstraction · Supports OpenAI and alternative hosted or local models. · `gpt_engineer/core/ai.py`
- [Default simple agent](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/simple_agent.py): agent implementation · `gpt_engineer/core/default/simple_agent.py`
- [Generation and improvement steps](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/steps.py): pipeline · Plans, generates, executes, and corrects code. · `gpt_engineer/core/default/steps.py`
- [Preprompt assets](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/preprompts/generate): prompt templates · Defines generation and improvement output conventions. · `gpt_engineer/preprompts/generate`
- [Preprompt loader](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/preprompts_holder.py): configuration layer · `gpt_engineer/core/preprompts_holder.py`
- [Chat-to-files parser](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/chat_to_files.py): model text boundary · Converts model output into file-oriented changes. · `gpt_engineer/core/chat_to_files.py`
- [Diff handler](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/diff.py): edit application · Applies improvement-mode edits to existing files. · `gpt_engineer/core/diff.py`
- [Disk memory and file store](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/file_store.py): persistent state · Persists conversation state and generated files. · `gpt_engineer/core/default/file_store.py`
- [Local execution environment](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/default/disk_execution_env.py): command runner · Runs AI-generated code in the target project. · `gpt_engineer/core/default/disk_execution_env.py`
- [Project operations](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/core/project_config.py): validation and tracking · Git, linting, project configuration, versioning, and token accounting. · `gpt_engineer/core/project_config.py`

### Benchmarking

- [Benchmark CLI](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/benchmark/__main__.py): CLI entry point · `gpt_engineer/benchmark/__main__.py`
- [Benchmark runner](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/benchmark/run.py): evaluation workflow · Runs configured agents against benchmark tasks. · `gpt_engineer/benchmark/run.py`
- [Benchmark datasets](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/gpt_engineer/benchmark/benchmarks/load.py): dataset adapters · Loads APPS and MBPP benchmark problems. · `gpt_engineer/benchmark/benchmarks/load.py`

### Delivery Runtime

- [Python package runtime](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/pyproject.toml): package metadata · Defines Python 3.10–3.12 packaging and installed commands. · `pyproject.toml`
- [Container runtime](https://github.com/gpt-engineer-org/gpt-engineer/blob/main/docker/Dockerfile): isolated runtime · Provides Docker and Compose execution surfaces. · `docker/Dockerfile`

### Other components

- **Target project directory**: filesystem boundary · Contains prompt, source context, generated edits, and execution effects.

## Connections

- Project CLI → CLI agent orchestration: starts
- Project CLI → Prompt and context collection: collects input
- Prompt and context collection → Target project directory: reads prompt and source tree
- CLI agent orchestration → Default simple agent: configures
- Default simple agent → Agent contracts: implements
- Default simple agent → Model providers: requests model output
- Default simple agent → Generation and improvement steps: runs
- Preprompt loader → Preprompt assets: loads
- Generation and improvement steps → Preprompt loader: uses conventions
- Generation and improvement steps → Chat-to-files parser: parses generated output
- Chat-to-files parser → Disk memory and file store: writes generated files
- Diff handler → Disk memory and file store: applies edits
- Disk memory and file store → Target project directory: materializes changes
- Generation and improvement steps → Local execution environment: executes and corrects
- Local execution environment → Target project directory: runs commands in
- Project operations → Target project directory: tracks and validates
- Benchmark CLI → Benchmark runner: starts
- Benchmark runner → Benchmark datasets: loads tasks
- Benchmark runner → Agent contracts: evaluates agents through
- Python package runtime → Project CLI: installs command
- Python package runtime → Benchmark CLI: installs command
- Container runtime → Python package runtime: packages runtime
