Feature: Add system prompt customization flags

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.

1. 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.

1. 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.

1. 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

• #10067 — --agents <name> flag for named AGENTS.md variants (complementary)
• #5983 — Ability to bypass/disable AGENTS.md pipeline
• #8759 — CLI fails to read AGENTS.md from global location
• #7138 — AGENTS.md silently truncated without warning

Additional information

_No response_