codex/docs/prompts.md

Custom Prompts

Save frequently used prompts as Markdown files and reuse them quickly from the slash menu.

• Location: Put files in $CODEX_HOME/prompts/ (defaults to ~/.codex/prompts/).
• File type: Only Markdown files with the .md extension are recognized.
• Name: The filename without the .md extension becomes the slash entry. For a file named my-prompt.md, type /my-prompt.
• Content: The file contents are sent as your message when you select the item in the slash popup and press Enter.
• Arguments: Local prompts support placeholders in their content:
  • $1..$9 expand to the first nine positional arguments typed after the slash name
  • $ARGUMENTS expands to all arguments joined by a single space
  • $$ is preserved literally
  • Quoted args: Wrap a single argument in double quotes to include spaces, e.g. /review "docs/My File.md".
  • File picker: While typing a slash command, type @ to open the file picker and fuzzy‑search files under the current working directory. Selecting a file inserts its path at the cursor; if it contains spaces it is auto‑quoted.
• How to use:
  • Start a new session (Codex loads custom prompts on session start).
  • In the composer, type / to open the slash popup and begin typing your prompt name.
  • Use Up/Down to select it. Press Enter to submit its contents, or Tab to autocomplete the name.
• Notes:
  • Files with names that collide with built‑in commands (e.g. /init) are ignored and won’t appear.
  • New or changed files are discovered on session start. If you add a new prompt while Codex is running, start a new session to pick it up.

Slash popup rendering

When you type /, the popup lists built‑in commands and your custom prompts. For custom prompts, the popup shows only:

• A five‑word excerpt from the first non‑empty line of the prompt file, rendered dim + italic.

Details:

• The excerpt strips simple Markdown markers (backticks, *, _, leading #) and any $1..$9/$ARGUMENTS placeholders before counting words. If the line is longer than five words, it ends with an ellipsis ….
• If frontmatter provides an argument-hint, it appears inline after the excerpt; otherwise only the excerpt is shown. Placeholders still expand when you submit the prompt.

Examples (illustrative):

• Prompt file perf-investigation.md starts with: Profile the slow path in module $1 → popup shows: /perf-investigation Profile the slow path in module
• Prompt file release-runbook.md starts with: Assemble release checklist for this service → popup shows: /release-runbook Assemble release checklist

Styling follows the Codex TUI conventions (command cyan + bold; excerpt dim + italic).

Frontmatter (optional)

Prompt files may start with a YAML‑style block to describe how the command should appear in the palette. The frontmatter is stripped before the prompt body is sent to the model.

---
description: "Run a post-incident retro"
argument-hint: "[incident-id] [severity]"
---
Draft a post-incident retrospective for incident $1 (severity $2).
List the timeline, impacted subsystems, contributing factors, and next steps.

With this file saved as incident-retro.md, the popup row shows:

• Name: /incident-retro
• Description: Run a post-incident retro
• Argument hint: [incident-id] [severity]

Argument examples

All arguments with $ARGUMENTS:

# search-codebase.md
Search the repository for $ARGUMENTS and summarize the files that need attention.

Usage: /search-codebase async runtime contention → $ARGUMENTS becomes "async runtime contention".

Individual arguments with $1, $2, …:

# hotfix-plan.md
Prepare a hotfix plan for bug $1 targeting branch $2.
Assign engineering owners: $3.
Include smoke tests and rollback steps.

Usage: /hotfix-plan BUG-1234 main "alice,bob" → $1 is "BUG-1234", $2 is "main", $3 is "alice,bob".