How to Configure Linting and Formatting Commands in gpt-engineer.toml

Add a [run] section to your gpt-engineer.toml file and set the lint and format keys to arbitrary shell commands (e.g., lint = "flake8 src", format = "black src") to enable automated code quality checks in GPT-Engineer.

GPT-Engineer, the open-source AI coding assistant from AntonOsika/gpt-engineer, uses a per-project configuration file called gpt-engineer.toml to customize its behavior. When you configure linting and formatting commands in this file, GPT-Engineer can automatically validate and style your codebase using your preferred tools, whether you are working with Python, JavaScript, or any other language.

Understanding the gpt-engineer.toml Configuration Structure

The configuration system is defined in gpt_engineer/core/project_config.py, where the Config dataclass parses your TOML file. Inside this file, the _RunConfig dataclass specifically handles shell commands under the [run] table:

@dataclass
class _RunConfig:
    build: str | None = None
    test: str | None = None
    lint: str | None = None
    format: str | None = None

The gpt-engineer.toml file must reside in your project root (the default filename is defined in the source as default_config_filename). When present, GPT-Engineer reads the [run] section and executes any defined commands via Python's subprocess module (as implemented in the CLI command-dispatch logic).

Configuring Linting Commands in gpt-engineer.toml

The lint key accepts any shell command string. When you run gpt engineer lint (or when the tool references run.lint during automated workflows), GPT-Engineer executes this command in your project directory.

Python example using flake8:

[run]
lint = "flake8 src --max-line-length=88"

JavaScript/TypeScript example using ESLint:

[run]
lint = "eslint . --ext .js,.ts,.tsx"

You can include flags, configuration file references, or environment variables. If the command fails (non-zero exit code), GPT-Engineer captures the output for review.

Configuring Formatting Commands in gpt-engineer.toml

The format key works identically to lint, but is triggered by gpt engineer format or automated formatting workflows. This command should modify files in-place to enforce style consistency.

Python example using black:

[run]
format = "black src/"

JavaScript example using Prettier:

[run]
format = "prettier --write ."

Rust example using rustfmt:

[run]
format = "cargo fmt"

Because the value is passed directly to subprocess, you can chain commands or use shell pipes if your platform supports them.

Complete Configuration Example

Here is a full gpt-engineer.toml demonstrating all [run] options, including build and test commands for context:

# gpt-engineer.toml

[run]

# Build step (optional)

build = "npm run build"

# Test suite (optional)

test = "npm run test"

# Linting command

lint = "eslint . --ext .js,.ts --config .eslintrc.json"

# Formatting command

format = "prettier --write \"**/*.{js,ts,json,md}\""

Place this file in your repository root. GPT-Engineer automatically detects it on startup and loads the commands into the Config.run object.

How GPT-Engineer Executes These Commands

When you invoke gpt engineer lint or gpt engineer format, the CLI dispatches to the corresponding handler in gpt_engineer/cli.py. This handler retrieves the command string from the loaded Config instance (parsed from gpt-engineer.toml) and executes it via Python's subprocess module.

If a command is not defined (the key is absent or set to null), the operation is a no-op—the CLI skips execution and continues. This design allows you to define only the workflows you need without requiring placeholder values.

Summary

• Configuration file: Create gpt-engineer.toml in your project root to customize GPT-Engineer behavior.
• Linting: Set the lint key under [run] to any shell command (e.g., flake8, eslint) to enable gpt engineer lint.
• Formatting: Set the format key under [run] to any in-place formatting command (e.g., black, prettier) to enable gpt engineer format.
• Execution: Commands are parsed by project_config.py and executed via subprocess in the CLI, with missing keys safely ignored.

Frequently Asked Questions

What is the default location for gpt-engineer.toml?

GPT-Engineer looks for gpt-engineer.toml in the project root directory by default. The specific filename is defined in the source code as default_config_filename within gpt_engineer/core/project_config.py. If the file is missing, GPT-Engineer operates with default empty values for all [run] commands.

Can I use environment variables in lint and format commands?

Yes. The values for lint and format are arbitrary shell command strings passed directly to Python's subprocess module. You can reference environment variables using your shell's syntax (e.g., $VAR or ${VAR} on Unix, %VAR% on Windows). GPT-Engineer does not expand these variables itself; it delegates execution to the system shell.

What happens if I omit the lint or format keys?

If the lint or format keys are absent from the [run] section, or if they are set to null, the corresponding CLI command becomes a no-op. When you run gpt engineer lint or gpt engineer format, the tool checks the loaded Config object (defined in project_config.py) and skips execution if the command string is missing, continuing without error.

Which linters and formatters work with gpt-engineer?

Any command-line linter or formatter that returns appropriate exit codes works with GPT-Engineer. Popular choices include flake8, pylint, or ruff for Python; ESLint or tslint for JavaScript/TypeScript; rubocop for Ruby; and gofmt for Go. Similarly, formatters like black, prettier, rustfmt, or **clang-format` are compatible. The tool simply executes your command string and captures the output.

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