Add `developer_instructions_file` for stronger local guidance

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

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 ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗