›_ Codex Issues
Codex Issues / #10067

Feature: Add --agents flag to switch between named AGENTS.md variants

Open 💬 5 comments Opened Jan 28, 2026 by lexobe
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

Summary

Add a --agents <name> CLI flag that allows users to switch between different named [AGENTS.md](<http://AGENTS.md>) files by name, e.g.:

codex --agents review "Review this PR"
codex --agents refactor "Clean up this module"
codex --agents debug "Find the root cause"

This would resolve to a file named AGENTS.<name>.md (or similar convention) in the standard discovery locations, rather than requiring the user to specify a full file path.

Motivation

Currently, Codex has a single [AGENTS.md](<http://AGENTS.md>) per directory level. There is no way to maintain multiple instruction sets for different workflows within the same project without renaming files or manipulating the filesystem each time.

Real-world use cases:

  • Code review vs. code generation: A reviewer agent needs different instructions (focus on bugs, security, style) than a feature-building agent (focus on patterns, tests, architecture).
  • Debugging vs. refactoring: Different tasks benefit from different system prompts — a debug agent should be methodical and trace-oriented, while a refactor agent should focus on readability and design patterns.
  • Team roles: Different team members may want different instruction sets — a frontend dev and a backend dev working on the same monorepo need different context.
  • CI/CD pipelines: Different pipeline stages (lint, review, generate tests) each need tailored instructions.

Proposed Behavior

File naming convention

AGENTS.md              # default (no --agents flag)
AGENTS.review.md       # codex --agents review
AGENTS.refactor.md     # codex --agents refactor
AGENTS.debug.md        # codex --agents debug

Discovery

Same directory-traversal logic as today, but at each level look for AGENTS.<name>.md (and AGENTS.<name>.override.md) instead of AGENTS.md:

  1. Global: ~/.codex/AGENTS.<name>.override.md → ~/.codex/AGENTS.<name>.md
  2. Project: Git root → CWD, checking AGENTS.<name>.override.md → AGENTS.<name>.md
  3. Fallback: If no named variant is found at a given level, optionally fall back to the plain AGENTS.md at that level (configurable behavior).

Examples

# Use the "review" instruction set
codex --agents review "Check this PR for security issues"

# Use the "refactor" instruction set
codex --agents refactor "Simplify the authentication module"

# Default behavior (unchanged, no flag)
codex "Implement the new feature"

# In non-interactive mode
codex exec --agents review -q "List all potential bugs" --json

Edge cases

  • Named file not found at any level → clear error: No AGENTS.review.md found in discovery path. Available variants: review, debug, refactor
  • List available variants: codex --list-agents could scan discovery paths and list all AGENTS.*.md files
  • Empty named file → skip silently (consistent with current behavior)

Why Not Just Use --profile?

Profiles (--profile <name>) already exist but control model and config settings (model name, reasoning effort, sandbox mode, etc.). Agent instructions are a separate concern — you may want the same model config but different instructions, or vice versa. Coupling them forces unnecessary duplication.

That said, profiles could also support an agents key:

[profiles.review]
model = "o3"
agents = "review"  # automatically implies --agents review

[profiles.quick-review]
model = "gpt-5-mini"
agents = "review"  # same instructions, cheaper model

Alternatives Considered

  • --agents-file <path>: Too low-level; forces users to manage paths rather than names. Doesn't integrate with the existing discovery hierarchy.
  • Symlinks / file renaming: Fragile, error-prone, no discoverability.
  • project_doc_fallback_filenames: Only controls fallback filenames, doesn't support explicit selection.
  • CODEX_HOME switching: Overkill — changes all global config just to swap instructions.

Related Issues

  • CLI-1219 — Ability to bypass/disable [AGENTS.md](<http://AGENTS.md>) pipeline (complementary)
  • CLI-2772 — CLI fails to read [AGENTS.md](<http://AGENTS.md>) from global location
  • CLI-1911 — [AGENTS.md](<http://AGENTS.md>) silently truncated without warning

View original on GitHub ↗

5 Comments

etraut-openai contributor · 7 months ago

Have you explored using skills for your use case? I think it mostly addresses what you're looking for with existing functionality.

evsukof · 6 months ago

Hi, I have a similar pain point and support the request from @lexobe . Having --agents would be highly beneficial for creating workflows.

kquinsland · 6 months ago
Have you explored using skills for your use case? I think it mostly addresses what you're looking for with existing functionality.

I have. Skills can approximate some aspects of this request but not others. Now that sub-agents are a bit less experimental with codex, I would _really_ like to be able to do something like this:

.
└── .codex/
    └── agents/
        ├── test-writer/
        │   ├── AGENTS.md    # Everything that only this sub-agent should know
        │   └── codex.toml     # Has the `model_reasoning_effort` and other settings as currently supported
        └── documetntarian/ ##
            ├── AGENTS.md   
            └── codex.toml

Then in my root/main/core (whatever you want to call it) AGENTS.md I can issue instructions akin to "review instructions in PROBLEM.md, use the documentarian sub-agent to help find and surface the appropriate documentation to understand the APIs and how they relate to the problem. Use the test-writer sub-agent to draft tests that use the targeted API as the spec/problem necessitate..."

isCopyman · 4 months ago

claude --agent can directly switch roles and configurations

MemoAsh · 1 month ago

I think skills cover the "named workflow" part of this better than more AGENTS.*.md variants, but only if the repo keeps a clean split:

  • AGENTS.md: stable repo-wide constraints and commands
  • skills/<workflow>/SKILL.md: task procedure, trigger, stop conditions, output shape
  • skills/<workflow>/verification.md: what must be checked before the agent says it is done

For the examples in this issue:

  • review becomes a review skill
  • debug becomes a reproduction/root-cause skill
  • refactor becomes a scoped refactor skill

The missing piece is often not the skill file itself, but a small verification contract. Without that, a "review" skill and a "debug" skill still degrade into long prompts.

I put together a tiny example repo showing this structure with a PR-review workflow and a safe-edit workflow:

https://github.com/MemoAsh/agent-workflow-pack

The pattern is intentionally simple: background rules in AGENTS.md, task behavior in SKILL.md, and completion criteria in verification.md.