# gpt-engineer User Guide

**gpt-engineer** is a command-line tool that turns a plain-English description into a working codebase. You write what you want in a single text file, run one command, and an AI model writes the source files, proposes a script to run them, and — with your permission — executes that script. You can also point it at an existing project and ask it to make changes.

This guide covers everything you need to install gpt-engineer, configure an AI model, generate and improve projects, and work with its specialized modes. It is written against gpt-engineer **0.3.1**.

> [!NOTE]
> gpt-engineer generates *and can execute* code written by a language model. Treat every generated project the way you would treat code from an untrusted source: read it before you run it, and prefer to run it in a throwaway folder or container. See [Generated code and safety](#9-generated-code-and-safety).

---

## 1. Quick Start

This is the shortest path from nothing to a generated project.

=== "Stable (PyPI)"

    ```bash
    python -m pip install gpt-engineer
    export OPENAI_API_KEY="sk-your-key-here"

    mkdir my-project
    echo "a simple command-line snake game in Python" > my-project/prompt

    gpte my-project
    ```

=== "From source (Poetry)"

    ```bash
    git clone https://github.com/gpt-engineer-org/gpt-engineer.git
    cd gpt-engineer
    poetry install
    poetry shell

    export OPENAI_API_KEY="sk-your-key-here"
    mkdir -p projects/my-project
    echo "a simple command-line snake game in Python" > projects/my-project/prompt

    gpte projects/my-project
    ```

What happens when you run `gpte my-project`:

1. gpt-engineer reads the `prompt` file in the folder you named.
2. The AI writes the code and prints each file as it goes.
3. The AI writes a `run.sh` script that installs dependencies and runs the code.
4. You are asked **`Do you want to execute this code? (Y/n)`** — press Enter to run it, or type `n` to skip.
5. Generated files are saved inside your project folder.

```text
Running gpt-engineer in /home/you/my-project

... (the AI streams the generated files here) ...

Do you want to execute this code? (Y/n)
```

> [!TIP]
> The command is available under three identical names: `gpte`, `ge`, and `gpt-engineer`. They are aliases for the same program. This guide uses `gpte`.

---

## 2. Installation

### 2.1 Requirements

| Requirement | Detail |
|---|---|
| Python | 3.10, 3.11, or 3.12 (declared range `>=3.10,<3.13`) |
| Operating system | Linux, macOS, or Windows |
| `git` | Recommended — used to snapshot your files before changes are written |
| An AI provider key | OpenAI, Anthropic, or Azure OpenAI (see [Section 3](#3-set-up-an-ai-model)) |

> [!NOTE]
> The last release to support Python 3.8–3.9 was `0.2.6`. On current releases you need Python 3.10 or newer.

### 2.2 Install the stable release

```bash
python -m pip install gpt-engineer
```

```text
Successfully installed gpt-engineer-0.3.1 ...
```

This installs the `gpte`, `ge`, `gpt-engineer`, and `bench` commands onto your `PATH`.

### 2.3 Install from source (for development or the latest code)

Source installs use [Poetry](https://python-poetry.org/):

```bash
git clone https://github.com/gpt-engineer-org/gpt-engineer.git
cd gpt-engineer
poetry install
poetry shell
```

`poetry shell` activates the virtual environment so the `gpte` command is on your `PATH`. If you prefer the bundled `Makefile`:

```bash
make install        # runs `poetry install` plus installs pre-commit hooks
```

### 2.4 Verify the install

```bash
gpte --help
```

```text
Usage: gpte [OPTIONS] [PROJECT_PATH]

  GPT-engineer lets you:

  - Specify a software in natural language
  - Sit back and watch as an AI writes and executes the code
  - Ask the AI to implement improvements
...
```

If you see the usage text, gpt-engineer is installed correctly. If the command is not found, see [Troubleshooting](#10-troubleshooting).

---

## 3. Set Up an AI Model

gpt-engineer talks to a language model through a provider API. You must supply at least one key. The default model is **`gpt-4o`** (OpenAI).

### 3.1 Provide a key

Choose **one** of these methods.

=== "Environment variable (Linux/macOS)"

    ```bash
    export OPENAI_API_KEY="sk-your-key-here"
    ```

    Add the line to `~/.bashrc` (or `~/.zshrc`) so you don't have to set it every session.

=== "Environment variable (Windows)"

    ```text
    set OPENAI_API_KEY=sk-your-key-here          (cmd)
    $env:OPENAI_API_KEY="sk-your-key-here"       (PowerShell)
    ```

=== ".env file"

    Create a file named `.env` in the directory you run gpt-engineer from. Start from the
    bundled template `.env.template`:

    ```bash
    OPENAI_API_KEY=sk-your-key-here
    ANTHROPIC_API_KEY=sk-ant-your-key-here
    ```

> [!IMPORTANT]
> If `OPENAI_API_KEY` is not already set in your environment, gpt-engineer automatically loads a `.env` file from your current working directory at startup. The same applies to `ANTHROPIC_API_KEY`.

### 3.2 Choose a provider and model

The provider is selected automatically from the model name you pass with `--model`/`-m`.

| You want | Set the model to | Key required | Notes |
|---|---|---|---|
| OpenAI (default) | `gpt-4o`, `gpt-4-turbo`, etc. | `OPENAI_API_KEY` | Default is `gpt-4o` |
| Anthropic Claude | any name containing `claude` | `ANTHROPIC_API_KEY` | Uses Claude via LangChain; capped at 4096 output tokens |
| Azure OpenAI | your **deployment name** | `OPENAI_API_KEY` | Also pass `--azure <endpoint>` |
| Local / alternative model | provider-specific | varies | See [Local & alternative models](#34-local-and-alternative-models) |

Examples:

```bash
gpte my-project --model gpt-4o
gpte my-project --model claude-3-5-sonnet-20240620
gpte my-project --model gpt-4-vision-preview        # vision-capable
```

> [!TIP]
> You can set a default model without typing `--model` every time by exporting the `MODEL_NAME` environment variable:
> ```bash
> export MODEL_NAME="claude-3-5-sonnet-20240620"
> ```

### 3.3 Azure OpenAI

For Azure, the value you pass to `--model` is the **deployment name** you chose in Azure AI Studio, and you must supply the service endpoint:

```bash
gpte my-project --model my-deployment-name \
  --azure "https://your-resource.openai.azure.com"
```

The Azure API version defaults to `2024-05-01-preview`. Override it with the `OPENAI_API_VERSION` environment variable if your resource requires a different version.

### 3.4 Local and alternative models

gpt-engineer can drive open-source models (for example, CodeLlama served locally) as long as they are exposed through an OpenAI-compatible API. This requires extra setup — running a local inference server such as `llama-cpp-python` and pointing the OpenAI client at it. The full procedure lives in the project's [open models documentation](https://gpt-engineer.readthedocs.io/en/latest/open_models.html); model configuration internals are covered in the Admin Guide.

> [!NOTE]
> When you run against a local model, set the `LOCAL_MODEL` environment variable so gpt-engineer prints `Total api cost: $ 0.0` instead of trying to compute a dollar cost.

---

## 4. Generate a New Project

This is the default mode — no flags required.

### 4.1 The `prompt` file

Every project lives in its own folder. Inside that folder you create a file named **`prompt`** (no file extension) containing your instructions in plain language.

```bash
mkdir todo-api
cat > todo-api/prompt <<'EOF'
A REST API for a todo list, written in Python with FastAPI.
It should support creating, listing, completing, and deleting todos.
Store todos in an in-memory list. Include a requirements.txt.
EOF
```

> [!TIP]
> Be specific about language, framework, and how the program should be run. The more concrete your prompt, the closer the result. gpt-engineer's built-in guidance already nudges the AI toward idiomatic structure (one class per file, a `requirements.txt` for Python, a `package.json` for Node, etc.).

### 4.2 Run it

```bash
gpte todo-api
```

```text
Running gpt-engineer in /home/you/todo-api

main.py
```python
from fastapi import FastAPI
...
```

requirements.txt
```text
fastapi
uvicorn
```

Do you want to execute this code? (Y/n)
```

Press Enter (or `y`) to let gpt-engineer run the generated `run.sh`; type `n` to keep the files without running them.

### 4.3 Where the output goes

Generated files are written **into your project folder**. gpt-engineer also creates a hidden `.gpteng/` directory there for its own bookkeeping (logs and metadata) — you can ignore it day to day.

| Path | What it is |
|---|---|
| `<project>/` | The generated source files |
| `<project>/run.sh` | The install-and-run script the AI produced |
| `<project>/.gpteng/memory/logs/` | Full transcripts of each step (useful for debugging) |

> [!NOTE]
> If a `git` repository is present (or gpt-engineer initializes one for you), your existing files are staged before new content overwrites them, so you can always diff or revert. See [Section 8](#8-your-files-are-protected-by-git).

---

## 5. Improve an Existing Project

Improve mode (`--improve` / `-i`) points gpt-engineer at code that already exists and applies targeted edits as diffs.

### 5.1 Run improve mode

Put a `prompt` file describing the change into the project folder, then:

```bash
gpte my-existing-project -i
```

The flow is:

1. **File selection.** gpt-engineer opens an editor with a list of every file in the project. You uncomment the files you want the AI to see and edit, save, and close.
2. **Linting.** Selected Python files are formatted with `black` before being sent (improves the quality of the AI's edits). You can turn this off — see below.
3. **Editing.** The AI returns its changes as a unified `git diff`, which gpt-engineer validates and applies.
4. **Review.** You see a colorized diff of exactly what will change and are asked **`Do you want to apply these changes?`**

### 5.2 The file-selection editor

When file selection opens, you see a TOML list. Lines beginning with `#` are **deselected**; remove the `#` to include a file:

```toml
# Remove '#' to select a file or turn off linting.
[files]
# "src/app.py" = "selected"
"src/models.py" = "selected"
# "tests/test_app.py" = "selected"
```

Save and close the editor to continue. gpt-engineer picks the editor from your `EDITOR` environment variable; if that is unset it tries `gedit`, `notepad`, `nvim`, `write`, `nano`, `vim`, and `emacs` in turn.

> [!TIP]
> Only select the files that are actually relevant to the change. Including unnecessary files costs tokens, can hit the model's context limit, and tends to *lower* the quality of the result.

To skip the interactive editor and reuse a previously saved selection, add `--skip-file-selection` (`-s`):

```bash
gpte my-existing-project -i -s
```

To disable `black` linting, uncomment the linting line in the selection file:

```toml
[linting]
"linting" = "off"
```

### 5.3 If no changes are applied

If the AI returns nothing usable, you'll see:

```text
No changes applied. Could you please upload the debug_log_file.txt in
<project>/.gpteng/memory/logs folder in a github issue?
```

This usually means the prompt was too vague or the wrong files were selected. Re-run, refine the prompt, and reselect files. If diffs are timing out, raise `--diff_timeout` (see [Section 7](#7-command-line-reference)).

---

## 6. Generation Modes

Beyond the default generate and improve flows, gpt-engineer offers modes that change *how* the AI works. Combine them with a project path like any other flag.

### 6.1 Clarify mode (`--clarify` / `-c`)

The AI reads your prompt and **asks clarifying questions** before writing any code. Answer in plain text, or type `c` to let it proceed on its own assumptions.

```bash
gpte my-project -c
```

```text
(answer in text, or "c" to move on)
Should the todo list persist between runs, or is in-memory storage fine?
> in-memory is fine
```

Use clarify mode when your requirements are loose and you want the AI to pin down the details with you first.

### 6.2 Lite mode (`--lite` / `-l`)

A fast, single-pass generation that uses **only your main prompt** with minimal scaffolding. No clarifying questions, no separate reasoning step.

```bash
gpte my-project -l
```

Use lite mode for small, well-specified tasks where you want speed and lower token usage.

### 6.3 Self-heal mode (`--self-heal` / `-sh`)

After generating the code, gpt-engineer runs it, and **if it fails, feeds the error output back to the AI to fix automatically** — repeating up to 10 times.

```bash
gpte my-project -sh
```

Use self-heal when you want a best-effort runnable result without babysitting each failure. Because it executes the generated code on each attempt, only use it in an environment you're comfortable running untrusted code in.

### 6.4 Vision mode (images as input)

Vision-capable models can read images alongside your text prompt — handy for handing the AI a UI mockup or architecture diagram. Point `--image_directory` at a folder of images and use a vision model:

```bash
gpte projects/example-vision gpt-4-vision-preview \
  --prompt_file prompt/text \
  --image_directory prompt/images \
  -i
```

> [!NOTE]
> Vision is detected from the model name. Models with `vision-preview`, non-preview `gpt-4-turbo`, or `claude` in the name are treated as vision-capable. If you supply images but use a non-vision model, the images are ignored.

### 6.5 Clipboard mode (`--llm-via-clipboard`)

For situations where you can't (or don't want to) call an API directly, clipboard mode copies the full prompt to your clipboard (and writes it to `clipboard.txt`). You paste it into a chat UI yourself, then paste the model's reply back into the terminal.

```bash
gpte my-project --llm-via-clipboard
```

```text
Enter/Paste your content. Ctrl-D or Ctrl-Z ( windows ) to save it.
```

### 6.6 Mode compatibility

> [!WARNING]
> **Improve mode cannot be combined with clarify or lite mode.** Running `gpte -i -c` or `gpte -i -l` exits with:
> ```text
> Error: Clarify and lite mode are not compatible with improve mode.
> ```

---

## 7. Command-Line Reference

Full option list for `gpte` / `ge` / `gpt-engineer`. The single positional argument is the project path.

| Argument | Type | Default | Purpose |
|---|---|---|---|
| `PROJECT_PATH` | path | `.` | Folder containing the `prompt` file and the generated/edited code |

| Option | Short | Default | Purpose |
|---|---|---|---|
| `--model` | `-m` | `gpt-4o` (or `$MODEL_NAME`) | Model ID string |
| `--temperature` | `-t` | `0.1` | Sampling randomness; lower is more deterministic |
| `--improve` | `-i` | off | Improve an existing project via diffs |
| `--lite` | `-l` | off | Single-pass generation from the main prompt only |
| `--clarify` | `-c` | off | Ask clarifying questions before generating |
| `--self-heal` | `-sh` | off | Auto-fix the code by re-running it on failure (up to 10 tries) |
| `--azure` | `-a` | `""` | Azure OpenAI endpoint URL |
| `--use-custom-preprompts` | | off | Use your project's own copy of the prompt templates |
| `--llm-via-clipboard` | | off | Exchange prompts/responses via the clipboard |
| `--verbose` | `-v` | off | Verbose (`DEBUG`-level) logging |
| `--debug` | `-d` | off | Drop into the `pdb` debugger on an unhandled exception |
| `--prompt_file` | | `prompt` | Relative path to the prompt text file |
| `--entrypoint_prompt` | | `""` | Relative path to a file specifying entrypoint requirements |
| `--image_directory` | | `""` | Relative path to a folder of images (vision) |
| `--use_cache` | | off | Cache LLM responses in `.langchain.db` to save tokens on reruns |
| `--skip-file-selection` | `-s` | off | Skip the interactive file picker in improve mode |
| `--no_execution` | | off | Set up but do not call the LLM or write code (for testing) |
| `--sysinfo` | | off | Print OS/Python/package info for bug reports, then exit |
| `--diff_timeout` | | `3` | Seconds before the diff-parsing regex times out |
| `--help` | `-h` | | Show help and exit |

### 7.1 Useful combinations

```bash
# Generate, asking questions first, with a specific model
gpte my-project -c -m gpt-4o

# Improve, reusing a saved file selection, with a longer diff timeout
gpte my-project -i -s --diff_timeout 10

# Cheap, repeatable runs while iterating on a prompt
gpte my-project --use_cache

# Collect environment details to paste into a bug report
gpte --sysinfo
```

> [!TIP]
> `--use_cache` stores responses keyed on the request, so running the same prompt again returns the cached answer instantly and for free. Delete `.langchain.db` to clear it.

---

## 8. Your Files Are Protected by Git

When gpt-engineer is about to overwrite files in a project that is a git repository, it first **stages your uncommitted changes**, so nothing is silently lost:

```text
Staging the following uncommitted files before overwriting:  src/app.py, README.md
```

In default (generate) mode, if the target folder is not yet a git repo, gpt-engineer initializes an empty one for you:

```text
Initializing an empty git repository
```

> [!TIP]
> After a run, use `git diff` (or `git stash list`) to see exactly what the AI changed, and `git checkout -- <file>` to revert anything you don't want.

---

## 9. Generated Code and Safety

gpt-engineer writes a `run.sh` script and offers to execute it. **This runs AI-generated commands on your machine.**

- You are always prompted before execution (`Do you want to execute this code? (Y/n)`). Type `n` to inspect first.
- Read `run.sh` and the generated files before running them, especially anything that installs packages or touches files outside the project.
- Prefer to generate into a fresh, empty folder — or run inside Docker (see the Admin Guide) — so a mistake can't damage unrelated work.
- During execution you can press `Ctrl+C` **once** to stop.

> [!CAUTION]
> Self-heal mode (`-sh`) executes the generated code repeatedly without pausing for each attempt. Only use it where running untrusted code is acceptable.

gpt-engineer can also send anonymized prompt data to its maintainers to improve the tool, but **only if you opt in**. The first time it would collect feedback it asks:

```text
Is it ok if we store your prompts to help improve GPT Engineer? (y/n)
```

Answering `n` disables collection. If you previously consented and change your mind, delete the `.gpte_consent` file in your working directory.

---

## 10. Troubleshooting

Each entry shows the exact message, its cause, and how to fix it.

### Error: `No files were selected. Please select at least one file to proceed.`
**Cause:** In improve mode, you saved the file-selection list without un-commenting any files.
**Solution:** Re-run `gpte <project> -i`. In the editor, remove the leading `#` from at least one file line, then save and close.
**Prevention:** Select only the relevant files, but make sure at least one is active.

### Error: `The path to the prompt, <path>, already exists as a directory.`
**Cause:** The value passed to `--prompt_file` points at a directory, not a text file.
**Solution:** Point `--prompt_file` at an actual file (the default is a file named `prompt`).

### Error: `The provided file at --entrypoint-prompt does not exist`
**Cause:** The `--entrypoint_prompt` path doesn't resolve to a file inside the project.
**Solution:** Use a path relative to the project folder that points to an existing file.

### Error: `The provided --image_directory is not a directory.` / `... is empty.`
**Cause:** `--image_directory` points at something that isn't a folder, or at an empty folder.
**Solution:** Pass a folder that exists and contains at least one image, and use a vision-capable model.

### Error: `The required entrypoint run.sh does not exist in the code.`
**Cause:** Execution or self-heal was requested but the AI did not produce a `run.sh`.
**Solution:** Re-run; if it recurs, make the prompt clearer about how the program should run, or provide `--entrypoint_prompt`.

### Error: `Clarify and lite mode are not compatible with improve mode.`
**Cause:** You combined `-i` with `-c` or `-l`.
**Solution:** Use improve mode on its own: `gpte <project> -i`.

### Message: `gpt-engineer timed out while parsing git diff`
**Cause:** In improve mode, the regex that parses the AI's diff exceeded the default 3-second budget on a large or complex diff.
**Solution:** Increase the budget, e.g. `--diff_timeout 10` (or higher).

### Message: `GPT did not provide any proposed changes.`
**Cause:** The model's reply contained no valid diff blocks.
**Solution:** Reselect the files for upload and refine the prompt to be more specific about the change you want.

### Issue: `gpte: command not found`
**Cause:** The console scripts aren't on your `PATH`.
**Solution:** If you installed from source, activate the environment with `poetry shell`. For a pip install, ensure your Python scripts directory is on `PATH`.

### Windows: `Could not locate file 'C:\Python311\Scripts\tqdm.exe'`
**Cause:** A known Windows packaging hiccup with a transitive dependency (community issue #874).
**Solution:** Reinstall the offending dependency, or run gpt-engineer inside Docker / WSL where the environment is clean.

### Error: `ValueError: too many values to unpack` / `issubclass() arg 1 must be a class`
**Cause:** Community-reported errors (issues #133, #1260) that have surfaced with certain model or dependency combinations.
**Solution:** Make sure you're on a supported Python (3.10–3.12) and the latest gpt-engineer; capture details with `gpte --sysinfo` when reporting.

> [!TIP]
> For any crash, run `gpte --sysinfo` and attach its output, plus `.gpteng/memory/logs/debug_log_file.txt` from your project, when filing an issue.

---

## 11. Frequently Asked Questions

**Q: What's the difference between `gpte`, `ge`, and `gpt-engineer`?**
Nothing — they are three names for the same command. Use whichever you prefer.

**Q: Do I need an OpenAI key, or can I use Claude / a local model?**
Any one provider is enough. Set `OPENAI_API_KEY` for OpenAI/Azure, `ANTHROPIC_API_KEY` for Claude, and choose the model with `--model`. Local models work with extra setup.

**Q: Where does the generated code end up?**
Directly in your project folder. gpt-engineer also writes a hidden `.gpteng/` folder there for logs and metadata.

**Q: How do I stop it from running the generated code automatically?**
Answer `n` at the `Do you want to execute this code? (Y/n)` prompt. Avoid `--self-heal`, which executes without pausing each time.

**Q: Can I see what the AI did, step by step?**
Yes. Look in `<project>/.gpteng/memory/logs/` — `all_output.txt`, `improve.txt`, `diff_errors.txt`, and `debug_log_file.txt` hold the full transcripts.

**Q: How do I keep costs down while iterating?**
Use `--use_cache` so repeated runs of the same prompt are free, prefer `--lite` for small tasks, and select only the files you need in improve mode.

**Q: Can I change the AI's "personality" or coding conventions?**
Yes. Pass `--use-custom-preprompts` to copy the prompt templates into your project, then edit them. This is how you make the agent remember conventions across projects. The templates are described in the Admin Guide.

**Q: It asked to store my prompts. Is that required?**
No. Data collection is opt-in. Answer `n`, or delete `.gpte_consent` to revoke a prior yes.

**Q: My diffs keep timing out in improve mode. What do I do?**
Raise `--diff_timeout` (e.g. `--diff_timeout 10`). The default is 3 seconds.

**Q: How do I run a benchmark against my own agent?**
gpt-engineer installs a separate `bench` command for evaluating agents against datasets like APPS and MBPP. That's an advanced/developer workflow — see the Admin Guide.

**Q: Is there a Docker option?**
Yes. The project ships a Dockerfile and `docker-compose.yml`. Setup and operational details are in the Admin Guide.

**Q: Which Python versions are supported?**
3.10, 3.11, and 3.12. For 3.8–3.9, use the older `0.2.6` release.

---

_Generated June 2026 from AntonOsika/gpt-engineer at a90fcd5. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._