Feature: Add system prompt customization flags

[lexobe]

What variant of Codex are you using?

code

What feature would you like to see?

Feature: Add system prompt customization flags (--system-prompt, --system-prompt-file, --append-system-prompt)

Summary

Add CLI flags that allow users to replace or extend the system prompt (including AGENTS.md content) from the command line, without modifying any files on disk.

Proposed flags:

# Completely replace system prompt with inline text
codex --system-prompt "You are a strict code reviewer. Focus on security." "Review this PR"

# Completely replace system prompt with a file
codex --system-prompt-file ./prompts/reviewer.md "Review this PR"

# Append to default system prompt (keep AGENTS.md + defaults)
codex --append-system-prompt "Always respond in Chinese." "Refactor this module"

# Append from file (keep defaults)
codex --append-system-prompt-file ./prompts/extra-rules.md "Fix the auth bug"

# Combine: replace base + append extras
codex --system-prompt-file ./prompts/base.md --append-system-prompt-file ./prompts/project-rules.md "Implement feature X"

Motivation

Currently, Codex only supports customizing agent instructions through AGENTS.md files placed in specific directories. This has several limitations:

1. No runtime switching: You cannot switch instruction sets without renaming or symlinking files on disk. This makes it impossible to use different personas (reviewer, debugger, refactorer) in a single session or script without filesystem manipulation.

2. CI/CD inflexibility: In automated pipelines, different stages (lint → review → test generation) need different instructions, but all share the same AGENTS.md. You'd have to generate AGENTS.md dynamically per step, which is fragile.

3. No ephemeral overrides: Sometimes you want a one-off instruction ("respond in Japanese", "be extra verbose", "ignore style rules for now") without polluting the project's AGENTS.md.

4. Team workflow friction: Different developers on the same repo may want personal instruction sets. Currently this requires ~/.codex/AGENTS.md at the global level only, with no per-invocation control.

Prior art: Claude Code

Claude Code (Anthropic's competing CLI agent) already ships exactly these four flags and they are heavily used in practice:

Claude Code flag	Purpose
--system-prompt	Replace entire system prompt with inline text
--system-prompt-file	Replace entire system prompt from a file
--append-system-prompt	Append inline text to default prompt
--append-system-prompt-file	Append file contents to default prompt

This is one of the most appreciated features in Claude Code's CLI, enabling workflows like:

# Claude Code examples that Codex cannot replicate today
claude --system-prompt-file ./prompts/review-agent.md "Check this PR"
claude --append-system-prompt "Use Japanese for all responses" "Explain this code"

Proposed Behavior

Flag definitions

Flag	Type	Mutually exclusive with	Description
--system-prompt	string	--system-prompt-file	Replace the entire system prompt (AGENTS.md content + defaults) with the given text
--system-prompt-file	path	--system-prompt	Replace the entire system prompt with file contents
--append-system-prompt	string	—	Append text after the default system prompt (AGENTS.md still loaded)
--append-system-prompt-file	path	—	Append file contents after the default system prompt

Precedence

1. If --system-prompt or --system-prompt-file is set → replace the AGENTS.md pipeline entirely
2. If --append-system-prompt or --append-system-prompt-file is set → append after normal AGENTS.md discovery
3. Both append flags can be combined (inline + file, concatenated in order)
4. A replace flag + an append flag can be combined (replace base, then append extras)

Integration with codex exec

These flags should also work in non-interactive mode:

codex exec --system-prompt-file ./prompts/ci-reviewer.md -q "List all bugs" --json
codex exec --append-system-prompt "Output as markdown table" "Summarize test coverage"

Integration with profiles

Profiles in config.toml could optionally set these:

[profiles.reviewer]
model = "o3"
system_prompt_file = "~/.codex/prompts/reviewer.md"

[profiles.quick-review]
model = "gpt-4.1-mini"
append_system_prompt = "Be concise. Skip style issues."

Why not --agents (Issue #10067)?

Issue #10067 proposes --agents <name> to resolve AGENTS.<name>.md files. While that's a valid approach for the naming convention, it doesn't cover several use cases:

Use case	--agents <name>	--system-prompt-file
Switch between pre-defined instruction sets	✅	✅
Use an arbitrary file path (outside project)	❌	✅
Inline one-off instruction override	❌	✅ (--system-prompt)
Append extra rules without replacing defaults	❌	✅ (--append-*)
Replace entire prompt for sandboxed/CI use	❌	✅
Combine base + extras from different sources	❌	✅

The two proposals are complementary: --agents is a convenient shorthand for named variants, while --system-prompt-file / --append-system-prompt-file provide full flexibility. Ideally both would be implemented.

Alternatives Considered

• project_doc_fallback_filenames: Config-level only, no runtime switching, no replace/append semantics.
• CODEX_HOME switching: Overkill — changes all global config just to swap instructions.
• Symlinks / file renaming: Fragile, error-prone, doesn't work in CI, no discoverability.
• -c system_prompt=... override: The system_prompt config key exists but is undocumented for CLI use and doesn't support the append workflow.

Related Issues

• Feature: Add --agents flag to switch between named AGENTS.md variants #10067 — --agents <name> flag for named AGENTS.md variants (complementary)
• Ability to bypass/disable AGENTS.md pipeline (CLI) #5983 — Ability to bypass/disable AGENTS.md pipeline
• CLI fails to read AGENTS.md from the global location by default #8759 — CLI fails to read AGENTS.md from global location
• AGENTS.md is silently truncated without any warning within the TUI #7138 — AGENTS.md silently truncated without warning

Additional information

No response

[miraclebakelaser]

Couple things to unpack: your request conflates AGENTS.md with system (developer) instructions. AGENTS.md isn't part of the system (developer) instructions – it's injected as a "user" message. @bolinfest wrote a nice blog post that goes into this in depth: Unrolling the Codex agent loop.

So, if you're looking to modify developer_instructions, you can already do most of your request out of the box. Try these:

• codex -c developer_instructions="Talk only in Japanese."

• non-interactive mode: codex -c developer_instructions="Talk only in Japanese." e "Give me a hello world in rust preceded by a meandering, 3-paragraph preamble."

• non-interactive mode with a prompt file: codex -c developer_instructions="$(cat ./prompts/review-agent.md)" e "Check this PR"

(If you're not familiar with OpenAI parlance, "developer instructions" are virtually the same as system instructions.)

If you're really just looking to modify AGENTS.md instead of developer_instructions, codex provides the flags to do exactly what you want. See the config reference.

[etraut-openai]

You can also use model_instructions_file to override AGENTS.md.

Most config keys can be overridden from the command line using the -c option.