codex-cli-best-practice

Skill by ara.so — Codex Skills collection.

A comprehensive guide and reference implementation for Codex CLI best practices, covering the journey from vibe coding to agentic engineering. This skill teaches you how to leverage Codex CLI's advanced features: subagents, skills, MCP servers, workflows, and configuration patterns.

What This Project Provides

codex-cli-best-practice is a reference repository that demonstrates:

Subagents: Custom TOML-configured agents for parallel orchestration
Skills: Reusable instruction packages with progressive disclosure
MCP Integration: Model Context Protocol servers for external tool access
Workflows: End-to-end patterns (Agent → Skill → Output)
Configuration: Layered TOML config system with profiles and approval policies
Hooks: Shell scripts that inject into the agentic loop
Memories: Cross-session memory pipeline for context retention

Installation

Prerequisites

Install Codex CLI (requires Codex Pro subscription):

# macOS
brew install --cask codex-cli

# Or download from https://developers.openai.com/codex/cli

Clone this repository:

git clone https://github.com/shanraisshan/codex-cli-best-practice.git
cd codex-cli-best-practice

Initialize Codex in your project:
```
codex init
```

Key Concepts & Configuration

1. Subagents (`.codex/agents/<name>.toml`)

Subagents are custom agents with dedicated role configs. Example weather agent:

# .codex/agents/weather-agent.toml
[agents.weather-agent]
model = "gpt-5.4"
instructions = """
You are a weather data specialist. When asked:
1. Extract location and units from user request
2. Fetch current weather from Open-Meteo API
3. Return structured data for downstream skills
"""
temperature = 0.7
max_tokens = 2000

Invoke with:

codex
> @weather-agent Get Dubai weather in Celsius

Global agent settings in .codex/config.toml:

[agents]
max_threads = 4
max_depth = 3
job_max_runtime_seconds = 300

2. Skills (`.agents/skills/<name>/SKILL.md`)

Skills are reusable instruction packages. Required structure:

.agents/skills/weather-svg-creator/
├── SKILL.md              # Core instructions with YAML frontmatter
├── scripts/              # Helper scripts
│   └── create_svg.py
├── references/           # Documentation
│   └── svg-spec.md
└── assets/              # Templates, images
    └── template.svg

Example SKILL.md:

---
name: weather-svg-creator
description: Creates SVG weather cards from structured weather data
---

# Weather SVG Creator

You create beautiful SVG weather cards. When invoked:

1. Accept weather data (location, temp, condition, humidity)
2. Use scripts/create_svg.py to generate SVG
3. Output to specified path

## Usage Pattern

```python
# scripts/create_svg.py will be called with:
python scripts/create_svg.py \
  --location "Dubai" \
  --temp "32" \
  --condition "Sunny" \
  --output "weather.svg"


Invoke skills:
```bash
# Explicit
codex
> Use $weather-svg-creator to make a card for Dubai, 32°C, Sunny

# Implicit (by description match)
> Create an SVG weather card

3. MCP Servers (`.codex/config.toml`)

Connect external tools via Model Context Protocol:

# .codex/config.toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/shan/projects"]
supports_parallel_tool_calls = true

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }

[mcp_servers.weather]
command = "python"
args = ["-m", "mcp_server_weather"]
working_directory = ".codex/mcp-servers/weather"

Manage MCP servers:

# List available servers
codex mcp list

# Add new server
codex mcp add weather

# Test server
codex mcp get weather

# OAuth login (for supported servers)
codex mcp login github

4. Orchestration Workflow (Agent → Skill)

The canonical pattern from this repo:

codex
> Fetch the current weather for Dubai in Celsius and create the SVG weather card output using the repo.

What happens:

@weather-agent fetches data from Open-Meteo
Returns structured JSON: {"location": "Dubai", "temp": 32, "condition": "Clear"}
Codex matches $weather-svg-creator skill by description
Skill runs scripts/create_svg.py with data
SVG output saved and displayed

5. Configuration Layers

# .codex/config.toml
[features]
memories = true           # Cross-session memory
codex_hooks = true       # Enable hooks
fast_mode = false        # 1.5x speed mode

[approval_policy]
edits_outside_cwd = "prompt"
deletions = "prompt"
shell_commands = "auto_approve_safe"

[sandbox]
enabled = true
include_patterns = ["src/**", "tests/**"]
exclude_patterns = ["*.pyc", "__pycache__/**"]

[model]
default = "gpt-5.4"
review_model = "gpt-5.4-large-context"
temperature = 0.7

[memories]
max_tokens = 10000
collection_interval_seconds = 300

# Developer instructions (always included)
developer_instructions = """
Follow repo conventions:
- Use type hints in Python
- Run pytest before committing
- Update AGENTS.md for architectural changes
"""

6. Hooks (`.codex/hooks.json`)

Inject shell scripts into the agentic loop:

{
  "hooks": {
    "before_edit": {
      "script": ".codex/hooks/lint-check.sh",
      "description": "Run linter before edits"
    },
    "after_shell": {
      "script": ".codex/hooks/log-command.sh",
      "description": "Log all shell commands"
    },
    "before_commit": {
      "script": ".codex/hooks/run-tests.sh",
      "description": "Run test suite"
    }
  }
}

Hook script example:

#!/bin/bash
# .codex/hooks/lint-check.sh

# Codex provides context via env vars:
# CODEX_HOOK_FILES, CODEX_HOOK_CONTEXT

for file in $CODEX_HOOK_FILES; do
  if [[ $file == *.py ]]; then
    ruff check "$file" || exit 1
  fi
done

exit 0

7. Plugins & Marketplace

Install plugin marketplaces:

# Add GitHub marketplace
codex plugin marketplace add github:openai/codex-plugins

# Add local marketplace
codex plugin marketplace add ~/my-plugins

# Browse installed plugins
codex
> /plugins

# Install specific plugin
codex plugin install security-scanner

Create a plugin (.codex-plugin/plugin.json):

{
  "name": "my-workflow-plugin",
  "version": "1.0.0",
  "description": "Custom workflow automation",
  "skills": ["skills/planner", "skills/executor"],
  "mcp_servers": {
    "custom-api": {
      "command": "node",
      "args": ["mcp-server.js"]
    }
  }
}

8. Memories (Cross-Session Context)

Enable in config:

[features]
memories = true

[memories]
max_tokens = 10000
collection_interval_seconds = 300

Control via TUI:

codex
> /memories use      # Enable for this session
> /memories reset    # Clear all memories

Memories are user-scoped, not project-scoped.

Common Workflows

Create a New Subagent

codex
> Create a subagent called @api-designer that specializes in REST API design. 
  It should use gpt-5.4-large-context and follow OpenAPI 3.0 standards.
  Save to .codex/agents/api-designer.toml

Create a New Skill

codex
> Use the $skill-creator to make a new skill called database-migrator.
  It should help write Alembic migrations for SQLAlchemy models.
  Include example migration scripts.

Set Up MCP Server for Custom Tool

# .codex/mcp-servers/weather/server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server

app = Server("weather-mcp")

@app.tool()
async def get_weather(location: str, units: str = "celsius"):
    """Fetch current weather for a location."""
    # Integration with Open-Meteo API
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.open-meteo.com/v1/forecast",
            params={
                "latitude": ...,
                "longitude": ...,
                "current_weather": "true",
                "temperature_unit": units
            }
        )
        return response.json()

if __name__ == "__main__":
    stdio_server(app)

Add to config:

[mcp_servers.weather]
command = "python"
args = [".codex/mcp-servers/weather/server.py"]

Implement Agent → Skill Workflow

Create the agent:

# .codex/agents/data-fetcher.toml
[agents.data-fetcher]
model = "gpt-5.4"
instructions = "Fetch data from APIs and return structured JSON"

Create the skill:

# .agents/skills/data-visualizer/SKILL.md
---
name: data-visualizer
description: Creates charts from JSON data
---

Accept JSON data and create matplotlib/plotly visualizations.

Invoke:

codex
> @data-fetcher get GitHub stars for shanraisshan/codex-cli-best-practice, 
  then $data-visualizer create a trend chart

Enable Fast Mode

codex
> /fast on         # Enable 1.5x speed (2x credits)
> /fast status     # Check current mode
> /fast off        # Disable

Or in config:

[model]
service_tier = "fast"  # Always use fast mode

Code Review Workflow

# Review uncommitted changes
codex
> /review

# Review specific branch
> /review main..feature-branch

# Review with custom instructions
> /review --instructions "Focus on security and performance"

Configure review model:

[model]
review_model = "gpt-5.4-large-context"

Slash Commands Reference

Command	Description
`/plan`	Create execution plan before acting
`/fast on\|off\|status`	Toggle fast mode (1.5x speed)
`/fork`	Create parallel session branch
`/review [ref]`	Code review for changes/branch
`/status`	Show session info and token usage
`/mcp`	Manage MCP servers
`/agent <name>`	Switch to specific subagent
`/apps`	Manage connected applications
`/model`	Change model for session
`/permissions`	Manage approval policies
`/skills`	Browse and invoke skills
`/plugins`	Browse plugin marketplace
`/memories use\|reset`	Control memory system

Environment Variables

# Required
export OPENAI_API_KEY="sk-..."  # Codex Pro API key

# Optional
export CODEX_HOME="$HOME/.codex"  # Config directory
export GITHUB_TOKEN="ghp_..."     # For GitHub MCP server
export ANTHROPIC_API_KEY="sk-..." # For Claude models (if configured)

Troubleshooting

Subagent Not Found

Issue: @my-agent not recognized

Solution:

# Check agent config exists
ls .codex/agents/my-agent.toml

# Verify TOML syntax
codex config validate

# Restart codex session
codex
> /exit
codex

Skill Not Triggering

Issue: Skill not invoked implicitly

Solution:

Use explicit invoke: $skill-name
Check skill description is specific enough
Verify SKILL.md has valid YAML frontmatter
Check .agents/skills/ directory structure

MCP Server Connection Failed

Issue: MCP server 'xyz' not responding

Solution:

# Test server directly
codex mcp get xyz

# Check server logs
cat ~/.codex/logs/mcp-xyz.log

# Verify command and args in config.toml
# Ensure env vars are set (use ${VAR} syntax)

# Restart server
codex mcp remove xyz
codex mcp add xyz

Hooks Not Running

Issue: Hooks defined but not executing

Solution:

# Enable in config
[features]
codex_hooks = true

# Make scripts executable
chmod +x .codex/hooks/*.sh

# Test hook directly
.codex/hooks/my-hook.sh

Memory Not Persisting

Issue: Context lost between sessions

Solution:

codex
> /memories use  # Enable for this thread

# Check feature flag
# In .codex/config.toml:
[features]
memories = true

Approval Policy Too Restrictive

Issue: Every action requires approval

Solution:

[approval_policy]
shell_commands = "auto_approve_safe"  # Auto-approve safe commands
edits_outside_cwd = "auto_approve"    # Less restrictive
network_access = "auto_approve"       # For MCP servers

# Or use profiles
[profiles.dev]
approval_policy.shell_commands = "auto_approve_safe"

Best Practices

Start with /plan: Let Codex create execution plans for complex tasks
Use AGENTS.md: Document project structure and conventions
Namespace subagents: Use descriptive names like @api-designer not @api
Scope skills narrowly: One skill = one clear responsibility
Test MCP servers: Use codex mcp get to verify before adding to workflow
Layer configs: Use profiles for different environments (dev, prod)
Enable hooks selectively: Start with after_shell for logging
Review approval policy: Balance security and automation
Use memories sparingly: Enable only for long-running projects
Document workflows: Create .md files showing Agent → Skill patterns

Resources

Official Docs: https://developers.openai.com/codex/overview
This Repo: https://github.com/shanraisshan/codex-cli-best-practice
MCP Spec: https://modelcontextprotocol.io
Community Skills: https://github.com/topics/codex-cli-skills
Plugin Marketplace: Built into Codex CLI (/plugins)

codex-cli-best-practice

codex-cli-best-practice

What This Project Provides

Installation

Prerequisites

Key Concepts & Configuration

1. Subagents (.codex/agents/<name>.toml)

2. Skills (.agents/skills/<name>/SKILL.md)

3. MCP Servers (.codex/config.toml)

4. Orchestration Workflow (Agent → Skill)

5. Configuration Layers

6. Hooks (.codex/hooks.json)

7. Plugins & Marketplace

8. Memories (Cross-Session Context)

Common Workflows

Create a New Subagent

Create a New Skill

Set Up MCP Server for Custom Tool

Implement Agent → Skill Workflow

Enable Fast Mode

Code Review Workflow

Slash Commands Reference

Environment Variables

Troubleshooting

Subagent Not Found

Skill Not Triggering

MCP Server Connection Failed

Hooks Not Running

Memory Not Persisting

Approval Policy Too Restrictive

Best Practices

Resources

1. Subagents (`.codex/agents/<name>.toml`)

2. Skills (`.agents/skills/<name>/SKILL.md`)

3. MCP Servers (`.codex/config.toml`)

6. Hooks (`.codex/hooks.json`)