# GPT Engineer Deep Dive

## What Is It?

**GPT Engineer** is the original AI code generation platform that transforms natural language into complete codebases. With **55.2k+ stars**, it pioneered the "describe and generate" approach to software development and evolved into the commercial platform Lovable.dev.

**Repository:** [AntonOsika/gpt-engineer](https://github.com/AntonOsika/gpt-engineer)

---

## The Problem It Solves

Traditional software development requires:
- Deep technical knowledge
- Manual translation of ideas to code
- Expertise in project structure and setup
- Time-intensive iteration

GPT Engineer provides:
- **Natural language to code** translation
- **Complete project generation** from descriptions
- **Iterative refinement** through conversation
- **Multi-model support** for different backends

---

## Key Statistics

| Metric | Value |
|--------|-------|
| **Stars** | 55,200 |
| **Forks** | 8,900 |
| **Contributors** | 200+ |
| **License** | MIT |
| **Commercial Version** | Lovable.dev |

---

## Core Concept: Preprompt System

GPT Engineer uses a **9-stage preprompt system** to guide code generation:

### Stage 1: Clarify

```
Ask clarifying questions about the project.
Identify ambiguities and edge cases.
Understand user requirements completely.
```

### Stage 2: Philosophy

```
Understand the purpose and goals.
Identify constraints and preferences.
Establish design principles.
```

### Stage 3: Roadmap

```
Create implementation plan.
Identify major components.
Establish order of operations.
```

### Stage 4: Entrypoint

```
Design the main entry point.
Structure the application bootstrap.
Define initialization flow.
```

### Stage 5: Generate

```
Create all necessary files.
Implement core functionality.
Build complete project structure.
```

### Stage 6: Spec

```
Document specifications.
Define interfaces.
Establish contracts.
```

### Stage 7: Respec

```
Refine specifications based on implementation.
Update documentation.
Align code with requirements.
```

### Stage 8: Unit Tests

```
Generate comprehensive tests.
Cover edge cases.
Ensure correctness.
```

### Stage 9: Improve

```
Refine generated code.
Optimize performance.
Apply best practices.
```

---

## Installation

### Basic Setup

```bash
# Install via pip
pip install gpt-engineer

# Or with pipx
pipx install gpt-engineer
```

### API Keys

```bash
# OpenAI (default)
export OPENAI_API_KEY=sk-...

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# Azure OpenAI
export AZURE_OPENAI_ENDPOINT=...
export AZURE_OPENAI_KEY=...
```

---

## Basic Usage

### Create a New Project

```bash
# Create project directory
mkdir my-project
cd my-project

# Create prompt file
echo "Create a simple Flask REST API with user authentication" > prompt

# Run GPT Engineer
gpte
```

### Project Structure

```
my-project/
├── prompt              # Your natural language description
├── workspace/          # Generated code output
│   ├── app.py
│   ├── requirements.txt
│   └── ...
└── memory/            # Context for iterations
```

### Iterate on Code

```bash
# After reviewing generated code
gpte --improve

# Or clarify further
echo "Add password reset functionality" >> prompt
gpte --improve
```

---

## Multi-Model Support

### Supported Providers

| Provider | Models | Configuration |
|----------|--------|---------------|
| **OpenAI** | GPT-4, GPT-4o, o1 | `OPENAI_API_KEY` |
| **Anthropic** | Claude 3.5 Sonnet, Opus | `ANTHROPIC_API_KEY` |
| **Azure** | Azure OpenAI | `AZURE_OPENAI_*` |
| **Local** | Ollama, vLLM | `OPENAI_API_BASE` |

### Switching Models

```bash
# Use Claude
gpte --model claude-3.5-sonnet

# Use GPT-4
gpte --model gpt-4

# Use local model
gpte --model ollama/codellama
```

---

## Example Projects

### Simple Web App

**prompt:**
```
Create a todo list web application with:
- HTML/CSS/JS frontend
- LocalStorage persistence
- Add, complete, and delete tasks
- Clean, modern UI
```

**Generated structure:**
```
workspace/
├── index.html
├── styles.css
├── app.js
└── README.md
```

### REST API

**prompt:**
```
Build a FastAPI backend for a blog:
- CRUD operations for posts
- SQLite database with SQLAlchemy
- Pydantic models for validation
- JWT authentication
```

**Generated structure:**
```
workspace/
├── main.py
├── models.py
├── schemas.py
├── auth.py
├── database.py
├── requirements.txt
└── README.md
```

### CLI Tool

**prompt:**
```
Create a command-line tool for managing git repositories:
- List all repos in a directory
- Show status summary
- Batch pull updates
- Use Click for CLI
```

**Generated structure:**
```
workspace/
├── gitmanager/
│   ├── __init__.py
│   ├── cli.py
│   └── repo.py
├── setup.py
└── README.md
```

---

## The Generation Process

```
┌─────────────────────────────────────────────────────────────┐
│                    User Prompt                              │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Clarification Phase                            │
│         (Ask questions, refine requirements)                │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                Planning Phase                               │
│      (Architecture, components, dependencies)               │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Generation Phase                               │
│          (Create all files atomically)                      │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│               Review & Improve                              │
│        (User feedback, iterate on code)                     │
└─────────────────────────────────────────────────────────────┘
```

---

## Vision Capability

GPT Engineer can generate code from images:

```bash
# Include image in prompt
echo "Create a UI based on the attached wireframe" > prompt

# Add image path
echo "image: wireframe.png" >> prompt

# Generate
gpte
```

### Use Cases

- Wireframe to code
- Screenshot to clone
- Diagram to implementation
- Design mockup to component

---

## Configuration

### Config File

```yaml
# .gpt-engineer/config.yaml

model: gpt-4o
temperature: 0.2

# Generation settings
max_tokens: 8000
auto_commit: true

# Features
vision: true
improve_mode: true
```

### CLI Options

| Flag | Description |
|------|-------------|
| `--model` | LLM to use |
| `--improve` | Iterate on existing code |
| `--steps` | Custom preprompt steps |
| `--vision` | Enable image input |
| `--temperature` | Generation creativity |

---

## Memory System

GPT Engineer maintains context across sessions:

```
memory/
├── specification      # Refined requirements
├── architecture       # Design decisions
├── files_list        # Generated file paths
└── feedback          # User feedback history
```

### Preserving Context

```bash
# Continue from previous session
gpte --resume

# Clear memory and start fresh
gpte --clear
```

---

## Evolution to Lovable.dev

GPT Engineer's success led to Lovable.dev:

### Key Differences

| Aspect | GPT Engineer | Lovable.dev |
|--------|--------------|-------------|
| **Interface** | CLI | Web-based |
| **Hosting** | Local | Cloud |
| **Deployment** | Manual | One-click |
| **Collaboration** | Git | Real-time |
| **Pricing** | Free (API costs) | Subscription |

### Shared DNA

- Natural language to code
- Iterative refinement
- Complete project generation
- Multi-technology support

---

## Best Practices

### Writing Effective Prompts

```
# Good Prompt
Create a Python Flask application for managing a small library:
- Books have: title, author, ISBN, status (available/borrowed)
- Users can: register, login, borrow books, return books
- Admin can: add/remove books, view all loans
- Use SQLite for storage
- Bootstrap for frontend
- Include basic CSS styling

# Bad Prompt
Make a library app
```

### Key Elements

1. **Specific features** - List what you need
2. **Technology choices** - Specify stack
3. **Data models** - Describe entities
4. **User roles** - Define permissions
5. **UI expectations** - Mention styling

### Iteration Strategy

```bash
# Step 1: Generate basic structure
gpte

# Step 2: Review and refine
# Add feedback to prompt
echo "
Improvements needed:
- Add input validation
- Better error messages
- Loading states in UI
" >> prompt

# Step 3: Improve
gpte --improve
```

---

## Comparison to Similar Tools

| Tool | Focus | Interface | Open Source |
|------|-------|-----------|-------------|
| **GPT Engineer** | Full projects | CLI | Yes |
| **Claude Code** | Agentic coding | CLI | No |
| **Aider** | Pair programming | CLI | Yes |
| **Cursor** | IDE integration | IDE | No |
| **Lovable** | Web apps | Web | No |

### GPT Engineer Strengths

1. **Batch generation** - Creates entire projects at once
2. **Clear workflow** - 9-stage preprompt system
3. **Open source** - Fully inspectable
4. **Multi-model** - Works with any LLM
5. **Lightweight** - Simple installation

---

## Advanced Usage

### Custom Preprompts

```python
# Create custom step
# .gpt-engineer/steps/my_step.py

def my_custom_step(ai, dbs):
    """Custom generation step"""
    messages = [
        {"role": "system", "content": "Custom system prompt"},
        {"role": "user", "content": dbs.input["prompt"]}
    ]
    response = ai.next(messages)
    return response
```

### Integration with CI/CD

```yaml
# .github/workflows/generate.yml
name: Generate Code

on:
  workflow_dispatch:
    inputs:
      prompt:
        description: 'What to build'
        required: true

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v4
      - name: Install GPT Engineer
        run: pip install gpt-engineer
      - name: Generate
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_KEY }}
        run: |
          echo "${{ inputs.prompt }}" > prompt
          gpte
```

---

## Troubleshooting

### Common Issues

| Issue | Solution |
|-------|----------|
| Rate limits | Use --model with cheaper option |
| Incomplete generation | Increase max_tokens |
| Wrong technology | Be explicit in prompt |
| Missing features | Use --improve for iterations |

### Debug Mode

```bash
gpte --verbose
# Shows full API exchanges
```

---

## Resources

- **Repository:** https://github.com/AntonOsika/gpt-engineer
- **Documentation:** https://gpt-engineer.readthedocs.io
- **Lovable.dev:** https://lovable.dev
- **Discord:** Active community

---

## Key Takeaways

1. **Natural language works** - Describe what you want
2. **Iteration is key** - Refine through feedback
3. **Prompts matter** - Be specific and detailed
4. **Multi-model flexibility** - Choose best LLM for task
5. **Projects, not files** - Generates complete codebases
6. **Evolution continues** - Now powers Lovable.dev

---

*GPT Engineer pioneered AI-driven code generation. While newer tools offer more features, understanding GPT Engineer's approach provides insight into how natural language can create complete software projects.*
