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

> Configure linting and formatting commands in gpt-engineer.toml easily. Set shell commands in the run section for automated code quality checks in GPT-Engineer.

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

---

**Add a `[run]` section to your [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/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`](https://github.com/AntonOsika/gpt-engineer/blob/main/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`](https://github.com/AntonOsika/gpt-engineer/blob/main/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:

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

```

The [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/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:**

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

```

**JavaScript/TypeScript example using ESLint:**

```toml
[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:**

```toml
[run]
format = "black src/"

```

**JavaScript example using Prettier:**

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

```

**Rust example using rustfmt:**

```toml
[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`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt-engineer.toml) demonstrating all `[run]` options, including build and test commands for context:

```toml

# 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`](https://github.com/AntonOsika/gpt-engineer/blob/main/gpt_engineer/cli.py). This handler retrieves the command string from the loaded `Config` instance (parsed from [`gpt-engineer.toml`](https://github.com/AntonOsika/gpt-engineer/blob/main/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`](https://github.com/AntonOsika/gpt-engineer/blob/main/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`](https://github.com/AntonOsika/gpt-engineer/blob/main/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`](https://github.com/AntonOsika/gpt-engineer/blob/main/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`](https://github.com/AntonOsika/gpt-engineer/blob/main/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`](https://github.com/AntonOsika/gpt-engineer/blob/main/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.