OpenAI Codex CLI Settings and Custom Prompts

A curated collection of configurations, skills and custom prompts for OpenAI Codex CLI, designed to enhance your development workflow with various model providers and reusable prompt templates.

For Claude Code settings, skills, agents and custom commands, please refer feiskyer/claude-code-settings.

Overview

This repository provides:

• Flexible Configuration: Support for multiple model providers (LiteLLM/Copilot proxy, ChatGPT subscription, Azure OpenAI, OpenRouter, ModelScope, Kimi)
• Custom Prompts: Reusable prompt templates for common development tasks
• Skills (Experimental): Discoverable instruction bundles for specialized tasks (image generation, YouTube transcription, spec-driven workflows)
• Best Practices: Pre-configured settings optimized for development workflows
• Easy Setup: Simple installation and configuration process

Quick Start

Installation

# Backup existing Codex configuration (if any)
mv ~/.codex ~/.codex.bak

# Clone this repository to ~/.codex
git clone https://github.com/feiskyer/codex-settings.git ~/.codex

# Or symlink if you prefer to keep it elsewhere
ln -s /path/to/codex-settings ~/.codex

Basic Configuration

The default config.toml uses LiteLLM as a gateway. To use it:

1. Install LiteLLM and Codex CLI:

   pip install -U 'litellm[proxy]'
   npm install -g @openai/codex
   

2. Create a LiteLLM config file (full example litellm_config.yaml):

   general_settings:
     master_key: sk-dummy
   litellm_settings:
     drop_params: true
   model_list:
   - model_name: gpt-5.1-codex-max
     model_info:
       mode: responses
       supports_vision: true
     litellm_params:
       model: github_copilot/gpt-5.1-codex-max
       drop_params: true
       extra_headers:
         editor-version: "vscode/1.95.0"
         editor-plugin-version: "copilot-chat/0.26.7"
   - model_name: claude-opus-4.5
     litellm_params:
       model: github_copilot/claude-opus-4.5
       drop_params: true
       extra_headers:
         editor-version: "vscode/1.95.0"
         editor-plugin-version: "copilot-chat/0.26.7"
   - model_name: "*"
     litellm_params:
       model: "github_copilot/*"
       extra_headers:
         editor-version: "vscode/1.95.0"
         editor-plugin-version: "copilot-chat/0.26.7"
   

3. Start LiteLLM proxy:

   litellm --config ~/.codex/litellm_config.yaml
   # Runs on http://localhost:4000 by default
   

4. Run Codex:

   codex
   

Configuration Files

Main Configuration

• config.toml: Default configuration using LiteLLM gateway
  • Model: gpt-5 via model_provider = "github" (Copilot proxy on http://localhost:4000)
  • Approval policy: on-request; reasoning summary: detailed; reasoning effort: high; raw agent reasoning visible
  • MCP servers: claude (local), exa (hosted), chrome (DevTools over npx)

Alternative Configurations

Located in configs/ directory:

• OpenAI ChatGPT: Use ChatGPT subscription provider
• Azure OpenAI: Use Azure OpenAI service provider
• Github Copilot: Use Github Copilot via LiteLLM proxy
• OpenRouter: Use OpenRouter provider
• Model Scope: Use ModelScope provider
• Kimi: Use Moonshot Kimi provider

To use an alternative config:

# Take ChatGPT for example
cp ~/.codex/configs/chatgpt.toml ~/.codex/config.toml
codex

Custom Prompts

Custom prompts are stored in the prompts/ directory. Access them via the /prompts: slash menu in Codex.

• /prompts:deep-reflector - Analyze development sessions to extract learnings, patterns, and improvements for future interactions.
• /prompts:insight-documenter [breakthrough] - Capture and document significant technical breakthroughs into reusable knowledge assets.
• /prompts:instruction-reflector - Analyze and improve Codex instructions in AGENTS.md based on conversation history.
• /prompts:github-issue-fixer [issue-number] - Systematically analyze, plan, and implement fixes for GitHub issues with PR creation.
• /prompts:github-pr-reviewer [pr-number] - Perform thorough GitHub pull request code analysis and review.
• /prompts:ui-engineer [requirements] - Create production-ready frontend solutions with modern UI/UX standards.
• /prompts:prompt-creator [requirements] - Create Codex custom prompts with proper structure and best practices.

Creating Custom Prompts

1. Create a new .md file in ~/.codex/prompts/
2. Use argument placeholders:
   • $1 to $9: Positional arguments
   • $ARGUMENTS: All arguments joined by spaces
   • $$: Literal dollar sign
3. Restart Codex to load new prompts

Skills (Experimental)

Skills are reusable instruction bundles that Codex automatically discovers at startup. Each skill has a name, description, and detailed instructions stored on disk. Codex injects only metadata (name, description, path) into context - the body stays on disk until needed.

How to Use Skills

Skills are automatically loaded when Codex starts. To use a skill:

1. List all skills: Use the /skills command to see all available skills

   /skills
   

2. Invoke a skill: Use $<skill-name> [prompt] to invoke a skill with an optional prompt

   $kiro-skill Create a feature spec for user authentication
   $nanobanana-skill Generate an image of a sunset over mountains
   

Skills are stored in ~/.codex/skills/**/SKILL.md. Only files named exactly SKILL.md are recognized.

Available Skills

# Start a new autonomous task
~/.codex/skills/autonomous-skill/scripts/run-session.sh "Build a REST API for todo app"

# Continue an existing task
~/.codex/skills/autonomous-skill/scripts/run-session.sh --task-name build-rest-api-todo --continue

# List all tasks
~/.codex/skills/autonomous-skill/scripts/run-session.sh --list

# Install spec-kit CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# Initialize project
specify init . --ai codex

Configuration Options

Approval Policies

• untrusted: Prompt for untrusted commands (recommended)
• on-failure: Only prompt when sandbox commands fail
• on-request: Model decides when to ask
• never: Auto-approve all commands (use with caution)

Sandbox Modes

• read-only: Can read files, no writes or network
• workspace-write: Can write to workspace, network configurable
• danger-full-access: Full system access (use in containers only)

Reasoning Settings

For reasoning-capable models (o3, gpt-5):

• Effort: minimal, low, medium, high
• Summary: auto, concise, detailed, none

Shell Environment

Control which environment variables are passed to subprocesses:

[shell_environment_policy]
inherit = "all"  # all, core, none
exclude = ["AWS_*", "AZURE_*"]  # Exclude patterns
set = { CI = "1" }  # Force-set values

Advanced Features

Profiles

Define multiple configuration profiles:

[profiles.openrouter]
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_provider = "openrouter"

[profiles.github]
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_provider = "github"

[model_providers.github]
name     = "OpenAI"
base_url = "http://localhost:4000"
http_headers = { "Authorization"= "Bearer sk-dummy"}
wire_api = "chat"

[model_providers.openrouter]
name     = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
http_headers = { "Authorization"= "Bearer [YOUR-API-KEY]"}
wire_api = "chat"

Use with: codex --profile openrouter

MCP Servers

Extend Codex with Model Context Protocol servers:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]

Project Documentation

Codex automatically reads AGENTS.md files in your project to understand context. Please always create one in your project root with /init command on your first codex run.

References

• Codex CLI Official Docs
• Codex GitHub Repository
• LiteLLM Documentation

Contributing

Contributions welcome! Feel free to:

• Add new custom prompts
• Share alternative configurations
• Improve documentation
• Report issues and suggest features

LICENSE

This project is released under MIT License - See LICENSE for details.