Is the Codex CLI capable of customizing the system prompt without recompiling the source code?

[doggy8088]

Does Codex CLI allows customization of system prompts without recompiling the source code?

[cpjet64]

• Yes for the main system prompt via config (no rebuild).
• No for the review and compaction prompts (rebuild required).

Runtime Overrides

• Main system prompt: override at runtime with either:
  • experimental_instructions_file in ~/.codex/config.toml (or -c experimental_instructions_file="path/to/prompt.md"). Code path: codex-rs/core/src/config.rs:906.
  • This replaces the compile-time BASE_INSTRUCTIONS loaded from codex-rs/core/prompt.md:1 via include_str! at codex-rs/core/src/client_common.rs:20.
• Project/user instructions: add AGENTS.md in your repo or in CODEX_HOME; these are read at session start and merged into input context (no rebuild). Code path: codex-rs/core/src/
  project_doc.rs:18, codex-rs/core/src/codex.rs:730.

Requires Rebuild

• Review prompt: compiled in from codex-rs/core/review_prompt.md:1 via include_str! (codex-rs/core/src/client_common.rs:23) and used for review threads at codex-rs/core/src/
  codex.rs:1548. Changing it requires rebuilding.
• Compaction/summarization prompt: compiled in from codex-rs/core/templates/compact/prompt.md:1 via include_str! (codex-rs/core/src/codex/compact.rs:31). Changing it requires rebuilding.

Usage Examples

• Override main system prompt for a run: codex -c experimental_instructions_file="/abs/path/my_prompt.md"
• Persist in ~/.codex/config.toml: add experimental_instructions_file = "/abs/path/my_prompt.md"

Notes

• Overrides are read when a new session starts; restart Codex/TUI/exec to pick up changes.
• There’s also a programmatic base_instructions_override path used internally (codex-rs/core/src/client_common.rs:36), but the CLI exposes the file-based override.

[BenBlumer]

There seems to be a check on the system prompt. When I create any custom prompt, e.g.

sys_p.md

You are Bob.

Then run codex:
codex -c experimental_instructions_file="sys_p.md"

I get errors about invalid instructions:

▌ Who are you?

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 1/5 in 210ms…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 2/5 in 386ms…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 3/5 in 740ms…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 4/5 in 1.754s…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 5/5 in 3.417s…

■ unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}

▌ what is 1+1?

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 1/5 in 180ms…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 2/5 in 412ms…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 3/5 in 755ms…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 4/5 in 1.63s…

⚠️ stream error: unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}; retrying 5/5 in 3.261s…

■ unexpected status 400 Bad Request: {"detail":"Instructions are not valid"}

Is there a way to circumvent this? Is there a minimum set of instructions required for the system prompt?