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

The 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 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 (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:

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:

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:

# 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:

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 from the current working directory:

# 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: Defines the TOML schema, Config dataclass hierarchy, and parsing logic (lines 34-79).
• gpt_engineer/applications/cli/main.py: CLI entry point that loads configuration before executing generation tasks.
• tests/test_project_config.py: Unit tests validating parsing accuracy and serialization round-trips.

The embedded example_config string in 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 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.
• 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 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 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:

[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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}