How gpt-engineer-org/gpt-engineer works
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: simple_agent.py Default simple agent · steps.py Generation and improvement steps · run.py Benchmark runner · main.py Project CLI
Components 20
Interactive CLI
- Project CLI
gpt_engineer/applications/cli/main.py - CLI agent orchestration
gpt_engineer/applications/cli/cli_agent.py - Prompt and context collection
gpt_engineer/applications/cli/collect.py
Agent Runtime
- Agent contracts · Separates agent behavior, model calls, memory, and execution.
gpt_engineer/core/base_agent.py - Model providers · Supports OpenAI and alternative hosted or local models.
gpt_engineer/core/ai.py - Default simple agent
gpt_engineer/core/default/simple_agent.py - Generation and improvement steps · Plans, generates, executes, and corrects code.
gpt_engineer/core/default/steps.py - Preprompt assets · Defines generation and improvement output conventions.
gpt_engineer/preprompts/generate - Preprompt loader
gpt_engineer/core/preprompts_holder.py - Chat-to-files parser · Converts model output into file-oriented changes.
gpt_engineer/core/chat_to_files.py - Diff handler · Applies improvement-mode edits to existing files.
gpt_engineer/core/diff.py - Disk memory and file store · Persists conversation state and generated files.
gpt_engineer/core/default/file_store.py - Local execution environment · Runs AI-generated code in the target project.
gpt_engineer/core/default/disk_execution_env.py - Project operations · Git, linting, project configuration, versioning, and token accounting.
gpt_engineer/core/project_config.py
Benchmarking
- Benchmark CLI
gpt_engineer/benchmark/__main__.py - Benchmark runner · Runs configured agents against benchmark tasks.
gpt_engineer/benchmark/run.py - Benchmark datasets · Loads APPS and MBPP benchmark problems.
gpt_engineer/benchmark/benchmarks/load.py
Delivery Runtime
- Python package runtime · Defines Python 3.10–3.12 packaging and installed commands.
pyproject.toml - Container runtime · Provides Docker and Compose execution surfaces.
docker/Dockerfile
Other components
- Target project directory · Contains prompt, source context, generated edits, and execution effects.
Connections 22
- 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