Support zero-config slash commands from .agents/commands/ and ~/.agents/commands/

What variant of Codex are you using?

CLI, App

What feature would you like to see?

As a Codex CLI user,
I want Codex to automatically discover slash commands from my project’s .agents/commands/ folder or my user home configuration in ~/.agents/commands/, so that I can define reusable project and personal commands without extra configuration, matching the workflow I get in tools like Pi Agent or OpenCode.

Additional information

Priority: High

### Acceptance Criteria

• [ ] Given a repository contains .agents/commands/review.md, when I start Codex in that repository, then the command is automatically available as /review without any

additional configuration.

• [ ] Given my home folder contains ~/.agents/commands/git-message.md, when I start Codex in any repository, then the command is automatically available as /git-message

without any additional configuration.

• [ ] Given a command file contains frontmatter with name, alias, description, and args, when Codex registers commands, then it uses that metadata to expose the command in

the slash-command interface.

• [ ] Given a command file has no valid frontmatter, when Codex scans .agents/commands/ or ~/.agents/commands/, then it falls back to the filename as the command name

where possible and reports a clear warning for invalid files.

• [ ] Given both project-level .agents/commands/ and user-level ~/.agents/commands/ define the same command name, when Codex registers commands, then the project-level

command takes precedence.

• [ ] Given neither .agents/commands/ nor ~/.agents/commands/ exists, when Codex starts, then startup behavior is unchanged and no warning is shown.
• [ ] Given a command is loaded from .agents/commands/ or ~/.agents/commands/, when I invoke it, then Codex executes the command instructions using the same permission and

sandbox rules as any other user instruction.

### Developer Tasks

| # | Task | Effort | Files / Modules |
|---|------|--------|-----------------|
| 1 | Locate the existing slash-command registration flow | S | [assumed] codex-cli command registry modules |
| 2 | Add scanner for project .agents/commands/*.md | M | [assumed] command discovery module |
| 3 | Add scanner for user ~/.agents/commands/*.md | S | [assumed] command discovery module |
| 4 | Parse command frontmatter and validate supported fields | M | [assumed] markdown/frontmatter parser |
| 5 | Implement precedence rules: built-in, user-level, project-level | M | [assumed] command registry module |
| 6 | Surface discovered commands in slash-command help/autocomplete | M | [assumed] TUI or command palette module |
| 7 | Add tests for valid commands, invalid frontmatter, missing folders, aliases, and conflicts | M | [assumed] command discovery tests |
| 8 | Document .agents/commands/ and ~/.agents/commands/ support with examples | S | docs/, README.md, or CLI docs |

### Definition of Done

• [ ] All acceptance criteria pass.
• [ ] Commands from .agents/commands/ work without explicit config.
• [ ] Commands from ~/.agents/commands/ work without explicit config.
• [ ] Project commands override user-level commands with the same name.
• [ ] Invalid command files fail gracefully with actionable diagnostics.
• [ ] Tests cover discovery, parsing, precedence, aliases, and missing-folder behavior.
• [ ] Documentation includes minimal examples for both project-level and user-level command files.