feat: introduce project- and user-scoped custom slash commands

[vjain419]

feat: introduce project- and user-scoped custom slash commands

Summary

This PR adds native support for reusable, project-scoped and user-specific custom slash commands via Markdown files in the TUI. Users can create prompts that are invoked in chat, e.g. /project:fix or /user:review__security.

---

Key Features

• Two command scopes:
  • Project-level: .codex/commands/ in the repo; shared across collaborators.
  • User-level: ~/.codex/commands/; follows the user globally.
• Simple templating: $ARGUMENTS in the Markdown file is replaced with the text after the command.
• Namespacing: Nested folders become double-underscores (e.g., review/security.md → /project:review__security).
• Automatic discovery: All custom commands are discovered at runtime and listed with built-ins in completion/help.
• Safe resolution: Only the two whitelisted roots are scanned, and project commands override user commands on collision, with a warning logged.

---

Implementation Details

• tui/src/custom_slash_command.rs:
  • All Rust logic for custom command expansion and discovery:
    • expand_custom_command: Looks up and expands command markdown, substituting $ARGUMENTS.
    • discover_custom_commands: Scans for all user/project commands for completion popup/help.
  • Includes unit tests for path mapping, argument handling, and collision logic.
• tui/src/bottom_pane/command_popup.rs:
  • Shows custom and built-in slash commands in interactive completion/help popups.
• tui/src/chatwidget.rs and tui/src/bottom_pane/chat_composer.rs:
  • Detect chat lines starting with /, expand if matching a custom command, and submit.
• No UI changes required: The TUI dynamically reflects changes in custom command lists.
• Design doc: See slash_command_plan.md for mapping, prefix, and security details.

---

Testing & Verification

• Unit/integration tests for:
  • Path→command mapping and namespacing.
  • Argument substitution in Markdown.
  • Scope collisions (project > user).
• Manual/E2E: Dropping a .md file in .codex/commands/ and using /project:<name> ... in-chat substitutes and sends the prompt as expected.

---

Summary:
This augments Codex TUI with a flexible and safe way for both teams and individuals to define, document, and re-use prompt templates as first-class slash commands

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[vjain419]

I have read the CLA Document and I hereby sign the CLA

[vjain419]

recheck

[bradford54]

hurry up !
we all need this pr

[am-will]

We already have this with /prompts don't we? If no, how will this differ? Thanks. #2696

They are not project scoped though. Would love to see that. Would love to see the ability to run bash commands, and launch parallel agents .

[vjain419]

@FreeMeWat
Good question! /prompts is definitely useful, but this PR adds value in ways /prompts doesn’t currently cover.

Not project scoped: Right now prompts are tied to individual users. With project-level prompts, we can share a consistent workflow across a project without everyone having to copy and maintain their own prompt library in their home area.

Prompt injection: /prompts doesn’t support inline injection, e.g. /prompt or /prompt performance=high debug=false. This PR will allow that kind of dynamic injection.

Additional options: Extending slash commands with extra user options, injection, and sharing at the project level makes it more powerful and collaborative.

It’s a bit of a shame that the OAI team went off and built their own version, but I still see this PR as valuable and complementary. I had paused the work since they were only accepting critical PRs until GA, but with GA done, I’ll be picking it back up this weekend (though I may need to rework quite a bit due to recent code changes).

[Bad3r]

@vjain419 there seems to be conflicts with main that needs to be addressed to make review/merging easier

[vjain419]

Hi @Bad3r yes I know :) I have tried to rebase in past very often but while talking OAI dev (on ent slack) I have been told to wait for this PR until GA milestone so I stopped doing rebase :P - I will rebase this weekend and ensure the changes still make sense/ right place in new code structure and put it out for review again. Hopefull this time it get merge in time. Thanks :)

[alexeydubinin]

Any updates? We all need this pr

[vjain419]

User Slash cmds already available in latest codex.

Project level prompts - they are not. Last I spoke to them(OpenAI dev) a month ago and they said they will add that support.

I would rather close this PR and track this via enhancement request.

[etraut-openai]

Thanks for the contribution, and apologies for the slow response. We've received many PRs, and we don't have the bandwidth on the codex team to review all of them.

We've updated our contribution guidelines to clarify that we're currently accepting contributions for bugs and security fixes, but we're not generally accepting new features at this time. We need to make sure that all new features compose well with both existing and upcoming features and fit into our roadmap. If you would like to propose a new feature, please file or upvote an enhancement request in the issue tracker. We will generally prioritize new features based on community feedback.