# Understanding the gpt-engineer.toml Configuration File Structure and Options

> Explore the gpt-engineer.toml file structure and options within the AntonOsika/gpt-engineer repository. Learn how to configure project settings, paths, and build commands for GPT-Engineer CLI and gptengineer.app.

- Repository: [Anton Osika/gpt-engineer](https://github.com/AntonOsika/gpt-engineer)
- Tags: how-to-guide
- Published: 2026-03-06

---

**The [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt-engineer.toml) file is a TOML-based configuration that stores project-specific settings for the GPT-Engineer CLI and `gptengineer.app`, defining paths, build commands, and OpenAPI integrations.**

The [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt-engineer.toml) configuration file controls how GPT-Engineer scans your codebase, executes post-generation commands, and integrates with external APIs. This file is central to the AntonOsika/gpt-engineer repository's workflow, enabling both the CLI and web application to operate with project-specific settings. Understanding its structure allows you to customize build pipelines and context gathering without modifying the tool's source code.

## Configuration Schema and Dataclass Architecture

The configuration schema is defined in **[`gpt_engineer/core/project_config.py`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt_engineer/core/project_config.py)** (lines 34-79) using Python dataclasses. The `Config` class serves as the root container, composed of three specialized sections that map directly to TOML tables:

| TOML Section | Dataclass | Purpose |
|--------------|-----------|---------|
| `[paths]` | `_PathsConfig` | Defines base directory and source subfolder for context scanning |
| `[run]` | `_RunConfig` | Specifies shell commands for build, test, lint, and format operations |
| `[gptengineer-app]` | `_GptEngineerAppConfig` | Stores `gptengineer.app` runtime settings including `project_id` and OpenAPI schema URLs |

Each dataclass enforces type safety, ensuring that required fields like `project_id` within the `[gptengineer-app]` section are present when that section is declared.

## Available Configuration Sections

### The [paths] Section

The `[paths]` section configures filesystem locations for context gathering. It supports two optional keys:

- **`base`**: The root directory of the project (defaults to current working directory). Useful for monorepos where GPT-Engineer should only scan a specific subtree.
- **`src`**: The subfolder whose files are fed to the LLM as context.

If omitted, these values default to `None`, and the system uses the current working directory as the project root.

### The [run] Section

The `[run]` section defines shell commands that GPT-Engineer executes automatically after code generation. These commands enable automated validation and formatting workflows:

- **`build`**: Command to compile or build the project (e.g., `npm run build`).
- **`test`**: Command to execute the test suite (e.g., `pytest -q`).
- **`lint`**: Command to run static analysis (e.g., `quick-lint-js`).
- **`format`**: Command to format code (e.g., `prettier --write .`).

Any command omitted from this section is skipped during the generation workflow.

### The [gptengineer-app] Section

The `[gptengineer-app]` section contains settings specific to the hosted `gptengineer.app` runtime:

- **`project_id`**: Required string identifier when using the managed service.
- **`openapi`**: Optional list of OpenAPI schema URLs that become part of the LLM context. Each entry is an object with a `url` key pointing to a JSON or YAML specification.

This section is only necessary when deploying to the GPT-Engineer platform rather than using the open-source CLI locally.

## Configuration Parsing and Serialization Workflow

The configuration system follows a strict three-phase lifecycle defined in [`gpt_engineer/core/project_config.py`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt_engineer/core/project_config.py):

1. **Reading**: The `read_config()` function loads the TOML file using **tomlkit**, returning a `TOMLDocument` object.
2. **Deserialization**: `Config.from_toml()` invokes `read_config()`, then `Config.from_dict()` constructs the three dataclass instances (`paths`, `run`, `gptengineer_app`), handling optional sections gracefully.
3. **Serialization**: `Config.to_toml()` writes configurations back to disk, utilizing the `filter_none()` routine to omit unset values and prevent empty sections from polluting the output file.

This design keeps configurations clean and prevents serialization of default `None` values, ensuring that manual edits to the TOML file remain readable.

## Practical Implementation Examples

### Loading a Configuration File Programmatically

Access configuration values through the `Config` class to inspect project settings:

```python
from pathlib import Path
from gpt_engineer.core.project_config import Config

config_path = Path("gpt-engineer.toml")
cfg = Config.from_toml(config_path)

print("Build command:", cfg.run.build)
print("Source root:", cfg.paths.src)
print("OpenAPI URLs:", [o.url for o in (cfg.gptengineer_app.openapi or [])])

```

The `Config` class automatically maps TOML sections into the `run`, `paths`, and `gptengineer_app` attributes, providing IDE-friendly autocomplete and type checking.

### Modifying and Persisting Configuration Changes

Update specific commands or add API specifications, then persist the changes:

```python

# Change the test command and add a new OpenAPI entry

cfg.run.test = "pytest -q"
if cfg.gptengineer_app:
    cfg.gptengineer_app.openapi.append(
        {"url": "https://new.api/openapi.json"}
    )

# Write back to the same file (overwrites only the changed parts)

cfg.to_toml("gpt-engineer.toml")

```

The `to_toml()` method preserves existing file structure while updating modified values, using **filter_none** to drop any unset configurations.

### Creating New Configurations Programmatically

Generate fresh configuration files for new projects or monorepo subdirectories:

```python
from gpt_engineer.core.project_config import Config, _RunConfig, _PathsConfig

new_cfg = Config(
    paths=_PathsConfig(base="./my-monorepo", src="./services/api"),
    run=_RunConfig(build="make build", test="make test", lint="make lint")
)

toml_str = new_cfg.to_toml("gpt-engineer.toml", save=False)
print(toml_str)   # inspect before persisting

```

Setting `save=False` returns the TOML string without writing to disk, useful for validation or preview workflows.

### CLI Integration and Automatic Loading

The GPT-Engineer CLI automatically discovers and loads [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt-engineer.toml) from the current working directory:

```bash

# The CLI reads gpt-engineer.toml and executes [run] commands after generation

gpt-engineer generate

```

When present, the CLI uses the defined `build`, `test`, and `lint` commands to validate generated code automatically.

## Key Source Files and Implementation Details

The configuration system is implemented across these critical files in the AntonOsika/gpt-engineer repository:

- **[`gpt_engineer/core/project_config.py`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt_engineer/core/project_config.py)**: Defines the TOML schema, `Config` dataclass hierarchy, and parsing logic (lines 34-79).
- **[`gpt_engineer/applications/cli/main.py`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt_engineer/applications/cli/main.py)**: CLI entry point that loads configuration before executing generation tasks.
- **[`tests/test_project_config.py`](https://github.com/AntonOsika/gpt-engineer/blob/main/tests/test_project_config.py)**: Unit tests validating parsing accuracy and serialization round-trips.

The embedded `example_config` string in [`project_config.py`](https://github.com/AntonOsika/gpt-engineer/blob/main/project_config.py) (lines 13-31) provides a ready-to-copy template demonstrating valid TOML syntax for all supported options.

## Summary

- The **[`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt-engineer.toml)** file uses TOML syntax to define project paths, build pipelines, and API integrations for GPT-Engineer.
- Configuration is parsed into type-safe **dataclasses** (`_PathsConfig`, `_RunConfig`, `_GptEngineerAppConfig`) defined in [`gpt_engineer/core/project_config.py`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt_engineer/core/project_config.py).
- The **`[run]`** section controls post-generation automation through `build`, `test`, `lint`, and `format` commands.
- The **`[gptengineer-app]`** section requires a `project_id` for the hosted service and supports OpenAPI schema integration.
- The **`Config.from_toml()`** and **`Config.to_toml()`** methods handle serialization using **tomlkit**, filtering out `None` values to maintain clean configuration files.

## Frequently Asked Questions

### Where should the gpt-engineer.toml file be located?

The GPT-Engineer CLI expects [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt-engineer.toml) in the current working directory where the `gpt-engineer generate` command is executed. The `base` key within the `[paths]` section can redirect the tool to a different project root if necessary, but the configuration file itself must reside in the execution context.

### Can I use GPT-Engineer without creating a configuration file?

Yes. All sections in [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt-engineer.toml) are optional. If the file is missing or specific keys are omitted, GPT-Engineer defaults to the current working directory for paths and skips automated build, test, and lint steps. The tool operates with sensible defaults when no configuration is present.

### How do I add multiple OpenAPI specifications to the context?

Define the `openapi` key as a TOML array of objects under the `[gptengineer-app]` section. Each object requires a `url` field pointing to a valid OpenAPI JSON or YAML specification:

```toml
[gptengineer-app]
project_id = "my-project"

openapi = [
    { url = "https://api.example.com/openapi.json" },
    { url = "https://another.service/spec.yaml" }
]

```

These schemas are automatically ingested into the LLM context when using the `gptengineer.app` platform.

### What happens if a command in the [run] section fails?

If a command defined in `[run]` (such as `build` or `test`) returns a non-zero exit code, GPT-Engineer captures the error output and typically includes it in the next LLM context iteration. The tool treats command failures as feedback for subsequent code generation attempts rather than fatal errors, allowing iterative refinement of the generated code.