### What variant of Codex are you using? CLI ### What feature would you like to see? I would like to propose a new config key: `developer_instructions_file`. This is a practical middle ground between: - `AGENTS.md`, which is useful but often has weaker adherence in practice, and - a hypothetical `--append-system-prompt-file`, which seems more invasive for Codex CLI. ### Additional information #### Context and problem I ran small local experiments and found that: - Guidance in `AGENTS.md`

Add `developer_instructions_file` for stronger local guidance

Resolved 💬 3 comments Opened Feb 26, 2026 by aofei Closed May 2, 2026

💡 Likely answer: A maintainer (aofei, contributor) responded on this thread — see the highlighted reply below.

What variant of Codex are you using?

CLI

What feature would you like to see?

I would like to propose a new config key: developer_instructions_file.

This is a practical middle ground between:

AGENTS.md, which is useful but often has weaker adherence in practice, and
a hypothetical --append-system-prompt-file, which seems more invasive for Codex CLI.

Additional information

Context and problem

I ran small local experiments and found that:

Guidance in AGENTS.md is not always followed consistently enough for strict workflows.
Guidance injected as developer instructions has much better adherence.

I also tried to emulate an "append system prompt file" flow using model_instructions_file, but that creates a maintenance burden:

I need to track and copy upstream base prompt content (for example from codex-rs/core/prompt.md and related model prompt behavior).
Any upstream changes to built-in instructions can break or drift my local setup.

Why this over `--append-system-prompt-file`

--append-system-prompt-file is appealing, but for Codex CLI it seems riskier:

It touches base/system instruction composition.
It can interact with model-specific templates and personality logic.

developer_instructions_file fits existing architecture better:

Lower implementation risk.
Clearer scope and intent.
Better adherence than AGENTS.md for strict local policy.

Compatibility

Fully backward compatible.
No behavior change unless explicitly configured.
Relationship with developer_instructions: developer_instructions_file provides a reusable baseline, while developer_instructions remains the inline per-config override.
If both are set, combine as: file_content + "\n\n" + developer_instructions, so inline text can refine or tighten the baseline file content.

View original on GitHub ↗

3 Comments

aofei contributor · 6 months ago

FWIW, what I want is a direct replacement for an existing Claude Code workflow that already works very well for me.

#!/usr/bin/env bash

set -e

claude="$(which -a claude | grep -v "$0" | head -1)"
system_prompt_file="${HOME}/.config/AGENTS.md"

for arg in "$@"; do
	if [[ "${arg}" == --append-system-prompt-file || "${arg}" == --append-system-prompt-file=* ]]; then
		exec "${claude}" "$@"
	fi
done

exec "${claude}" --append-system-prompt-file "${system_prompt_file}" "$@"

etraut-openai contributor · 3 months ago

This feature request hasn't received enough upvotes, so I'm closing it.

hlky · 2 months ago

@etraut-openai Would you consider reopening/revisiting this request?

I put together a branch implementing developer_instructions_file for my own use, and wanted to share it in case it reduces the amount of OpenAI engineering bandwidth needed to evaluate the feature:

I understand this may not have enough broad demand to prioritize internally. My hope is that having an implementation available makes it easier to assess whether the feature is acceptable, even if it still needs changes before it could be considered.

My personal use case is easier experimentation with and sharing of custom developer instructions. I will likely use this together with:

include_permissions_instructions = false
include_apps_instructions = false
include_collaboration_mode_instructions = false

[skills]
include_instructions = false

The reason is that I want to experiment with completely custom developer instructions while suppressing the default developer-instruction sections. I suspect that interactions between the default developer-instruction sections and parts of the base/system instructions can sometimes compound into assumptions that affect the quality of the work produced. For that kind of experiment, keeping a large amount of Markdown inside config.toml is awkward, and sharing it is also awkward.

model_instructions_file already solves this shape of problem for model/base instructions: it lets users provide substantial custom instructions without flooding config.toml with hundreds of lines. This branch adds the analogous config key for developer instructions.

The branch is intended to be backward compatible: no behavior changes unless developer_instructions_file is configured. It also updates the config schema and adds test coverage for config loading, profile/path resolution, standalone agent roles, config lock behavior, and a request-body integration test showing the file content is sent as a developer role message.

I'm happy to adjust the exact semantics if maintainers prefer a different precedence or combination behavior.