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:

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

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:

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