mirror of
https://github.com/openai/codex.git
synced 2026-11-10 21:00:47 +00:00
Evan David
f7da902be3
Key features - Custom prompts accept arguments: $1..$9, $ARGUMENTS, and $$ (literal) - @ file picker in composer: type @ to fuzzy‑search and insert quoted paths - Frontmatter hints: optional description + argument-hint shown in palette (body stripped before send) Why - Make saved prompts reusable with runtime parameters. - Improve discoverability with concise, helpful hints in the slash popup. - Preserve privacy and approvals; no auto‑execution added. Details - Protocol: extend CustomPrompt with description, argument_hint (optional). - Core: parse minimal YAML‑style frontmatter at file top; strip it from the submitted body. - TUI: expand arguments; insert @ paths; render description/argument-hint or fallback excerpt. - Docs: prompts.md updated with frontmatter and argument examples. Tests - Frontmatter parsing (description/argument-hint extracted; body stripped). - Popup rows show description + argument-hint; excerpt fallback; builtin name collision. - Argument expansion for $1..$9, $ARGUMENTS, $$; quoted args and @ path insertion. Safety / Approvals - No changes to approvals or sandboxing; prompts do not auto‑run tools. Related - Closes #2890 - Related #3265 - Complements #3403
80 lines
3.8 KiB
Markdown
80 lines
3.8 KiB
Markdown
## 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"`.
|