How to Configure Custom Prompts in the Codex CLI: A Complete Guide

You configure custom prompts in the Codex CLI by creating a YAML (or JSON) file that maps short names to full prompt texts, then pointing the CLI to that file via the --prompt-file flag or the CODEX_PROMPT_FILE environment variable.

The openai/codex repository provides a flexible system for managing reusable system prompts. By configuring custom prompts, you can standardize repetitive tasks—such as lint fixing or code review—across both interactive and automated workflows without retyping lengthy instructions.

Creating a Custom Prompt Definition File

Custom prompts are stored in a definition file that maps identifiers to prompt content. According to the documentation in docs/prompts.md, the file supports YAML or JSON format and requires two fields per entry: description (a human-readable summary) and prompt (the full instruction text).

Create a file at ~/.config/codex/prompts.yaml with the following structure:

# ~/.config/codex/prompts.yaml

fix_lint:
  description: "Fix lint errors in the current project"
  prompt: |
    You are a lint-fixing assistant.
    • Analyze the current repository.
    • Identify all lint violations.
    • Generate the minimal set of changes to make the code pass `cargo fmt` and `cargo clippy`.

review_pr:
  description: "Review a pull-request"
  prompt: |
    Act as a senior engineer reviewing a PR.
    • Summarize the change.
    • Point out potential bugs, style issues, or missing tests.
    • Suggest improvements.

Each top-level key (fix_lint, review_pr) becomes the command name you invoke later.

Configuring the CLI to Locate Your Prompts

The Codex CLI must know where to find your definition file. As implemented in the codex-cli source, you have two configuration options:

Environment Variable (Persistent) Set CODEX_PROMPT_FILE to the absolute path in your shell configuration:

export CODEX_PROMPT_FILE=$HOME/.config/codex/prompts.yaml

Command-Line Flag (Per-Invocation) Pass the path explicitly using --prompt-file:

codex exec --prompt-file $HOME/.config/codex/prompts.yaml "fix_lint"

If both are provided, the command-line flag typically takes precedence, though you should verify behavior in codex-cli/README.md for your specific version.

Using Custom Prompts in Interactive and Batch Mode

Once configured, you invoke prompts by name. The CLI expands the short name into the full prompt text before sending it to the model.

Interactive REPL Usage

In the TUI chat composer (documented in docs/tui-chat-composer.md), type the slash command /prompts: followed by the prompt name:

codex
> /prompts: fix_lint

The composer automatically expands this into the full prompt text defined in your YAML file.

Batch Execution (Full-Auto Mode)

For non-interactive automation with codex exec, reference the prompt name as the argument:

codex exec --prompt-file $HOME/.config/codex/prompts.yaml "review_pr"

This allows unattended workflows where the CLI runs entirely without user interaction.

Inline One-Off Prompts

For ad-hoc tasks that do not warrant a permanent definition file, use the --prompt flag to embed the instruction directly:

codex exec --prompt "You are a helpful assistant that writes unit tests for the given Rust function." "$(cat src/lib.rs)"

Managing and Discovering Available Prompts

To view all prompts defined in the currently loaded prompt file, use the codex prompts sub-command as described in codex-cli/README.md:

codex prompts list

# or

codex prompts ls

This outputs the names and descriptions of every entry in your prompts.yaml, helping you verify which shortcuts are available before invoking them.

Summary

• Create a YAML file with named entries containing description and prompt fields.
• Configure the path via CODEX_PROMPT_FILE environment variable or --prompt-file flag.
• Invoke prompts by name using /prompts: name in the REPL or codex exec "name" in scripts.
• List available prompts anytime with codex prompts list to verify your configuration.
• Use --prompt for single-use instructions without creating a definition file.

Frequently Asked Questions

What file format does Codex CLI use for custom prompts?

The Codex CLI accepts both YAML and JSON formats for prompt definition files. The file must contain top-level keys that map to objects with description and prompt fields, as documented in docs/prompts.md.

Can I store my prompt file in a different directory than ~/.config/codex?

Yes. You can place the file anywhere on your filesystem. You must tell the CLI where to find it by either setting the CODEX_PROMPT_FILE environment variable to the absolute path or passing the --prompt-file flag with every invocation.

How do I use a custom prompt without creating a definition file?

For one-off tasks, use the --prompt flag with codex exec followed by the literal prompt text in quotes. This bypasses the need for a YAML file entirely, though the prompt will not be reusable across sessions without retyping it.

Why does my prompt name not expand in the TUI composer?

Ensure you are using the exact syntax /prompts: name (with the colon and space) as specified in docs/tui-chat-composer.md. Also verify that your CODEX_PROMPT_FILE environment variable is set in the same shell session where you launched codex, or that you launched the CLI with the --prompt-file flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}