### CSV Batch Processing Example

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

This example demonstrates how to use `spawn_agents_on_csv` for batch processing. It involves creating a CSV file, defining instructions with placeholders, and specifying output schema and paths.

```shell
Create /tmp/components.csv with columns path,owner and one row per frontend component.

Then call spawn_agents_on_csv with:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk,
  summary, and follow_up via report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: an object with required string fields path, risk, summary, and follow_up
```

--------------------------------

### Optional Metadata with agents/openai.yaml

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/docs/SKILLS.md

Provides an example of `agents/openai.yaml` for defining optional UI, policy, and dependency metadata for a skill.

```yaml
interface:
  display_name: "Docs Helper"
  short_description: "Verifies framework APIs before code changes"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: mcp
      value: openaiDeveloperDocs
      description: OpenAI Docs MCP server
      transport: streamable_http
      url: https://developers.openai.com/mcp
```

--------------------------------

### Example Codex CLI Command

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/README.md

This is an example of how to interact with the Codex CLI to fetch weather data and generate an SVG output.

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

```

--------------------------------

### Git Commit Convention Example

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/AGENTS.md

Illustrates the 'one file, one commit' Git convention for maintaining a clean and manageable commit history. Each code example shows adding and committing a single file.

```bash
git add README.md
git commit -m "Update README.md with project overview"
```

```bash
git add best-practice/codex-agents-md.md
git commit -m "Add/update Codex Agents MD best practices"
```

```bash
git add .agents/skills/weather-svg-creator/SKILL.md
git commit -m "Update weather SVG creator skill"
```

--------------------------------

### Minimal `marketplace.json` Manifest

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md

A basic example of a `marketplace.json` manifest file. It includes the required `name` field and a list of plugins with their local sources.

```json
{
  "name": "my-marketplace",
  "plugins": [
    { "name": "release-notes", "source": "./plugins/release-notes" }
  ]
}
```

--------------------------------

### Skill Directory Structure Example

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/docs/SKILLS.md

Illustrates the typical file and directory structure for a Codex skill, including required and optional components.

```text
.agents/skills/
  my-skill/
    SKILL.md
    scripts/
    references/
    assets/
    agents/
      openai.yaml
```

--------------------------------

### Example Subagent Prompt

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Use this prompt to instruct Codex to spawn a subagent for each review point and summarize their results.

```plaintext
I would like to review the following points on the current PR (this branch vs main).
Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race conditions
5. Test flakiness
6. Maintainability of the code
```

--------------------------------

### Full Codex CLI Hook Configuration Example

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-hooks.md

This JSON demonstrates a comprehensive configuration for various Codex CLI hooks, including SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, and Stop.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py\"",
            "statusMessage": "Reviewing Bash output"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/user_prompt_submit.py\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_continue.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Git Commit Convention Example

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/CLAUDE.md

Demonstrates the 'one file, one commit' strategy for maintaining a clean and manageable Git history. Each change to a file should result in a separate commit.

```bash
git add README.md
- Commit 1: git add README.md -> commit with README-specific message
git add best-practice/codex-agents-md.md
- Commit 2: git add best-practice/codex-agents-md.md -> commit with agents-doc-specific message
git add .agents/skills/weather-svg-creator/SKILL.md
- Commit 3: git add .agents/skills/weather-svg-creator/SKILL.md -> commit with skill-specific message
```

--------------------------------

### Example `config.toml` Entry for a Marketplace

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md

This TOML snippet shows how Codex CLI records marketplace information in its configuration file. It includes source details, reference, sparse paths, and update timestamps.

```toml
[marketplaces.my-marketplace]
source_type   = "git"
source        = "https://github.com/owner/repo.git"
ref           = "main"
sparse_paths  = ["plugins/toolkit"]
last_updated  = "2026-04-18T00:00:00Z"
last_revision = "abc123..."
```

--------------------------------

### Full-Shape `marketplace.json` Manifest

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md

An extensive example of a `marketplace.json` manifest, showcasing various `source` types (local, remote URL, git-subdir) and optional fields like `interface`, `policy`, and `category`.

```json
{
  "name": "codex-curated",
  "interface": { "displayName": "Codex Curated" },
  "plugins": [
    {
      "name": "local-plugin",
      "source": "./plugins/local-plugin"
    },
    {
      "name": "remote-subdir",
      "source": {
        "source": "git-subdir",
        "url": "openai/joey_marketplace",
        "path": "plugins/toolkit",
        "ref": "main"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL",
        "products": ["codex_cli"]
      },
      "category": "dev-tools"
    },
    {
      "name": "remote-url",
      "source": {
        "source": "url",
        "url": "https://github.com/owner/repo.git",
        "ref": "main"
      }
    }
  ]
}
```

--------------------------------

### Codex Prompt for PR Review

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Example prompt to initiate a PR review using the configured agents. This prompt directs the pr_explorer, reviewer, and docs_researcher agents to perform their specific tasks.

```text
Review this branch against main. Have pr_explorer map the affected code paths,
reviewer find real risks, and docs_researcher verify the framework APIs
that the patch relies on.
```

--------------------------------

### Path Resolution for Repo-Local Hooks

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-hooks.md

Prefer git-root-based paths for hooks to ensure stability when Codex starts from subdirectories.

```bash
/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/script.py"
```

--------------------------------

### Codex Agent Path Addressing Example

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Illustrates the hierarchical path-based addressing system for Codex agents, showing how child agents extend the parent path. This system is primarily for tool-facing interactions.

```text
/root                       # the root session
/root/task1                 # spawned from root
/root/task1/reviewer        # spawned from /root/task1
```

--------------------------------

### Launching Secure Devcontainer

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Starts a hardened VS Code Dev Container environment for running Codex against untrusted code. This uses separate configuration files, not `config.toml` profiles.

```bash
devcontainer up --workspace-folder . \
  --config .devcontainer/devcontainer.secure.json
```

--------------------------------

### Run Weather Agent Orchestration

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/CLAUDE.md

This command initiates the weather agent to fetch data and trigger the SVG rendering skill. Ensure Codex CLI is installed and configured.

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

--------------------------------

### Stop Hook Decision Example

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-hooks.md

Use this JSON to instruct Codex to continue processing after a turn completes. The 'reason' field provides text for the next prompt.

```json
{
  "decision": "block",
  "reason": "continuation reason text"
}
```

--------------------------------

### Codex Prompt for Frontend Debugging

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Example prompt to investigate UI regressions. This prompt instructs the browser_debugger, code_mapper, and ui_fixer agents to work together to reproduce, trace, and fix the issue.

```text
Investigate why the settings modal fails to save. Have browser_debugger reproduce it,
code_mapper trace the responsible code path, and ui_fixer implement the smallest fix
once the failure mode is clear.
```

--------------------------------

### Adding Marketplaces with Different Source Types

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md

Illustrates various ways to specify the source for a plugin marketplace. This includes GitHub shorthand, Git URLs, SSH URLs, and local directory paths.

```bash
codex plugin marketplace add owner/repo
```

```bash
codex plugin marketplace add https://github.com/owner/repo.git
```

```bash
codex plugin marketplace add git@github.com:owner/repo.git
```

```bash
codex plugin marketplace add /abs/path/to/marketplace
```

```bash
codex plugin marketplace add ./vendor/internal-market
```

--------------------------------

### Configure MCP Filesystem and GitHub Servers

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md

Define MCP servers for filesystem and GitHub access in your `.codex/config.toml`. Use `npx` to run the respective servers and set environment variables like `GITHUB_TOKEN` if needed.

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

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

--------------------------------

### Partial Clone with Sparse Checkout

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md

Demonstrates how to use the `--sparse` option to fetch only specific subdirectories from a large marketplace repository. This is useful for reducing download size and improving performance.

```bash
codex plugin marketplace add openai/marketplace-big \
  --sparse plugins/toolkit \
  --sparse skills/release-notes
```

--------------------------------

### Skill Directory Structure

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-skills.md

Organize skill files within the '.agents/skills/' directory. Core instructions go in SKILL.md, references in 'references/', deterministic helpers in 'scripts/', and UI/policy metadata in 'agents/openai.yaml'.

```text
.agents/skills/
  docs-helper/
    SKILL.md
    references/
    scripts/
    assets/
    agents/
      openai.yaml
```

--------------------------------

### SessionStart Hook Output for Context

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-hooks.md

For the `SessionStart` event, plain text on stdout is added as developer context. JSON output allows for structured data, including `additionalContext`.

```json
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "text added as context"
  }
}
```

--------------------------------

### Minimal SKILL.md Frontmatter

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/docs/SKILLS.md

Shows the minimum required YAML frontmatter for a `SKILL.md` file, including name and description.

```markdown
---
name: my-skill
description: Explain exactly when this skill should and should not trigger.
---

# My Skill

Instructions Codex should follow when this skill is activated.
```

--------------------------------

### Configuring MCP Servers

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Declares shared integrations like the GitHub server, specifying the command, arguments, and environment variables required to run it.

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

--------------------------------

### Configure Frontend Debugging Agents

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Set up agents for UI regressions and cross-stack bugs: a code mapper, a browser debugger, and a UI fixer. Configure sandbox modes and MCP server URLs as needed.

```toml
name = "code_mapper"
description = "Read-only codebase explorer for locating relevant frontend and backend code paths."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = ""
Map the code that owns the failing UI flow.
Identify entry points, state transitions, and likely files before the worker starts editing.
"
```

```toml
name = "browser_debugger"
description = "UI debugger that uses browser tooling to reproduce issues and capture evidence."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = ""
Reproduce the issue in the browser, capture exact steps, and report what the UI actually does.
Use browser tooling for screenshots, console output, and network evidence.
Do not edit application code.
"

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
startup_timeout_sec = 20
```

```toml
name = "ui_fixer"
description = "Implementation-focused agent for small, targeted fixes after the issue is understood."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
developer_instructions = ""
Own the fix once the issue is reproduced.
Make the smallest defensible change, keep unrelated files untouched,
and validate only the behavior you changed.
"

[[skills.config]]
path = "/Users/me/.agents/skills/docs-editor/SKILL.md"
enabled = false
```

--------------------------------

### Configure MCP Apps with Tool Settings

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md

Define MCP applications and their tool configurations, including approval modes and enablement status. This allows for fine-grained control over how specific app tools are used.

```toml
[apps.my_app]
enabled                     = true
default_tools_approval_mode = "prompt"   # auto | prompt | approve
default_tools_enabled       = true
destructive_enabled         = false
open_world_enabled          = false

[apps.my_app.tools.send_email]
approval_mode = "prompt"
enabled       = true
```

--------------------------------

### Minimal Skill Frontmatter

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-skills.md

Use only the required 'name' and 'description' fields in the frontmatter for a skill. Add more only if there's a documented reason.

```yaml
---
name: docs-helper
description: Verify framework API details before making code changes or writing migration guidance.
---
```

--------------------------------

### Memory Extension Structure

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-memory.md

Illustrates the directory structure for memory extensions, including persistent instructions and transient per-run artifacts. Resource files are auto-pruned after 7 days.

```bash
$CODEX_HOME/memories_extensions/
└── <extension_name>/
    ├── instructions.md              # always loaded if present
    └── resources/
        └── 2026-04-18T14-32-05-notes.md   # per-run artifact, auto-pruned
```

--------------------------------

### Core Configuration Settings

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Defines fundamental settings like the AI model, sandbox mode, and approval policy for a project. Place this in `.codex/config.toml`.

```toml
# .codex/config.toml
model = "o4-mini"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

--------------------------------

### Allowing Unix Sockets in Development Permissions

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Enables network access and specifically allows Unix sockets for the 'development' permission profile. Paths are matched as subpath prefixes.

```toml
[permissions.development.network]
enabled = true

[permissions.development.network.unix_sockets]
"/tmp/example.sock"        = "allow"
"/var/run/myservice.sock"  = "allow"
```

--------------------------------

### List Agents Tool

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Use `list_agents` to retrieve a list of live agents. This can be optionally filtered by `path_prefix`. The returned agent status includes values like `pending_init`, `running`, `interrupted`, `shutdown`, `not_found`, `completed`, or `errored`.

```shell
list_agents
```

--------------------------------

### Configure PR Review Agents

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Set up three specialized agents for PR reviews: a read-only explorer, a correctness reviewer, and a documentation researcher. Ensure the correct model and sandbox modes are specified.

```toml
[agents]
max_threads = 6
max_depth = 1
```

```toml
name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = ""
Stay in exploration mode.
Trace the real execution path, cite files and symbols, and avoid proposing fixes
unless the parent agent asks for them.
Prefer fast search and targeted file reads over broad scans.
"
```

```toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = ""
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
Lead with concrete findings, include reproduction steps when possible,
and avoid style-only comments unless they hide a real bug.
"
```

```toml
name = "docs_researcher"
description = "Documentation specialist that uses the docs MCP server to verify APIs and framework behavior."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = ""
Use the docs MCP server to confirm APIs, options, and version-specific behavior.
Return concise answers with links or exact references when available.
Do not make code changes.
"

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"
```

--------------------------------

### Run Weather Agent Orchestration

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/AGENTS.md

This command initiates the weather agent to fetch data and render an SVG card. It demonstrates the Agent → Skill orchestration pattern.

```bash
codex
```

--------------------------------

### Followup Task Tool

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Use `followup_task` to enqueue a message and trigger a turn. Setting `interrupt: true` will preempt the current turn.

```shell
followup_task
```

--------------------------------

### Optional Skill Metadata with OpenAI Agent

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-skills.md

Use 'agents/openai.yaml' for richer metadata like display names, short descriptions, and invocation policies. Set 'allow_implicit_invocation' to false to disable implicit triggering.

```yaml
interface:
  display_name: "Docs Helper"
  short_description: "Checks APIs before code changes"

policy:
  allow_implicit_invocation: false
```

--------------------------------

### Profile Configurations

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Sets up named profiles for different development or operational needs, allowing quick switching between configurations. These can be defined in `config.toml`.

```toml
[profiles.conservative]
sandbox_mode = "read-only"
approval_policy = "untrusted"
```

```toml
[profiles.development]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
```

```toml
[profiles.ci]
model = "o4-mini"
sandbox_mode = "read-only"
approval_policy = "never"
```

```toml
[profiles.trusted]
sandbox_mode = "danger-full-access"
approval_policy = "never"
```

--------------------------------

### Codex CLI Marketplace Commands

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-marketplace.md

These are the primary commands for interacting with the Codex CLI plugin marketplace. Use `add` to register a new marketplace, `upgrade` to update existing ones, and `remove` to uninstall.

```bash
codex plugin marketplace add <SOURCE> [--ref <REF>] [--sparse <PATH>]...
codex plugin marketplace upgrade [MARKETPLACE_NAME]
codex plugin marketplace remove <MARKETPLACE_NAME>
```

--------------------------------

### Memories Configuration Options

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-memory.md

Configure various aspects of the memories feature, including usage, generation, consolidation models, and limits. All keys are optional and have default values.

```toml
[memories]
use_memories                       = true     # inject into future sessions
generate_memories                  = true     # record threads as generation input
consolidation_model                = "gpt-5.4"        # Phase 2 model
extract_model                      = "gpt-5.4-mini"   # Phase 1 model
max_raw_memories_for_consolidation = 256      # cap 4096
max_rollout_age_days               = 30       # clamp 0..=90
max_rollouts_per_startup           = 16       # cap 128
max_unused_days                    = 30       # drives memory-extension cleanup (0..=365)
min_rollout_idle_hours             = 6        # clamp 1..=48
no_memories_if_mcp_or_web_search   = false    # privacy guard
```

--------------------------------

### Spawn Agent Tool

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Use `spawn_agent` to create a child agent. It returns the task name and nickname of the spawned agent.

```shell
spawn_agent
```

--------------------------------

### Custom Agent TOML Configuration

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Define a custom agent with its name, description, developer instructions, and nickname candidates. Nicknames are for display only.

```toml
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]
```

--------------------------------

### Resume Agent Tool

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Use `resume_agent` to restart a previously closed agent using its ID.

```shell
resume_agent
```

--------------------------------

### Execute Weather Workflow via CLI

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/orchestration-workflow/orchestration-workflow.md

Demonstrates how to trigger the weather orchestration workflow using the Codex CLI. The user provides a natural language prompt specifying the location and unit preference, which the agent then processes.

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

--------------------------------

### Enable Parallel Tool Calls for MCP Servers

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md

Configure an MCP server to support parallel tool calls by setting `supports_parallel_tool_calls = true`. This should only be used for servers where tools are safe to run concurrently.

```toml
[mcp_servers.docs]
command = "docs-server"
supports_parallel_tool_calls = true
```

--------------------------------

### Enable Memories in Config

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-memory.md

Enable the memories feature by setting `memories = true` in the `[features]` section of your `config.toml` file. This is required to use the memories functionality.

```toml
[features]
memories = true
```

--------------------------------

### Sandbox-State Metadata Configuration

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md

An MCP server can advertise `codex/sandbox-state-meta` to enable sandbox-state metadata. This augments `tools/call` with details like `sandboxPolicy`, `codexLinuxSandboxExe`, `sandboxCwd`, and `useLegacyLandlock`.

```json
{
  "codex/sandbox-state-meta": {
    "sandboxPolicy": { "...": "..." },
    "codexLinuxSandboxExe": "/path/to/codex-linux-sandbox",
    "sandboxCwd": "/workspace",
    "useLegacyLandlock": false
  }
}
```

--------------------------------

### Registering Agents

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Defines custom agents, providing a description and optionally pointing to a dedicated configuration file for specialized tasks.

```toml
[agents.backend-dev]
description = "Handles backend implementation tasks"
config_file = "agents/backend-dev.toml"
```

--------------------------------

### Good vs. Bad Skill Descriptions

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-skills.md

Write specific descriptions that act as precise trigger conditions for skills. Avoid vague descriptions that match too broadly.

```yaml
# Good
description: Review TypeScript changes for type-safety regressions and missing runtime validation.

# Bad
description: Help with TypeScript.
```

--------------------------------

### CSV Batch Processing (Experimental)

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Utilize `spawn_agents_on_csv` for processing multiple similar tasks, where each row in a CSV file represents a work item.

```APIDOC
## CSV Batch Processing (Experimental)

Use `spawn_agents_on_csv` for many similar tasks that map to one row per work item. Codex reads the CSV, spawns one worker per row, waits for the batch to finish, and exports combined results.

### Good for:

- Reviewing one file, package, or service per row.
- Checking lists of incidents, PRs, or migration targets.
- Generating structured summaries for many similar inputs.

### Parameters

| Parameter | Purpose |
|---|---|
| `csv_path` | Source CSV file path. |
| `instruction` | Worker prompt template with `{column_name}` placeholders. |
| `id_column` | Column containing stable item IDs. |
| `output_schema` | JSON object schema that each worker must return. |
| `output_csv_path` | Path for exporting results. |
| `max_concurrency` | Limit for parallel workers. |
| `max_runtime_seconds` | Timeout for each worker in seconds. |

Each worker must call `report_agent_job_result` exactly once. If a worker exits without reporting, Codex marks that row with an error.

### Example Prompt and Usage

```
Create /tmp/components.csv with columns path,owner and one row per frontend component.

Then call spawn_agents_on_csv with:
- csv_path: /tmp/components.csv
- id_column: path
- instruction: "Review {path} owned by {owner}. Return JSON with keys path, risk, summary, and follow_up via report_agent_job_result."
- output_csv_path: /tmp/components-review.csv
- output_schema: an object with required string fields path, risk, summary, and follow_up
```
```

--------------------------------

### Send Message Tool

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-subagents.md

Use `send_message` to enqueue a message to an existing agent without triggering a turn.

```shell
send_message
```

--------------------------------

### Disable Skill Configuration

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/docs/SKILLS.md

Demonstrates how to disable a specific skill by adding an entry to the `~/.codex/config.toml` file. Requires a Codex restart after changes.

```toml
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false
```

--------------------------------

### Run Codex as an MCP Server

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md

Execute the Codex CLI as an MCP server using the `codex mcp-server` command. This allows other applications to interact with Codex as an MCP service.

```bash
codex mcp-server
```

--------------------------------

### One-Off Configuration Overrides

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Applies temporary configuration changes for a single command execution using the `-c` flag. This allows for quick adjustments without modifying the main config file.

```bash
codex -c model=\"o3\" -c approval_policy=\"never\" exec "summarize this diff"
```

--------------------------------

### Enable Hooks in config.toml

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-hooks.md

To enable the hooks feature, set `codex_hooks` to `true` in the `[features]` section of your `config.toml` file.

```toml
[features]
codex_hooks = true
```

--------------------------------

### Enabling Memories Feature

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-config.md

Activates the cross-session memory pipeline for enhanced context retention. Configure this under the `[features]` and `[memories]` sections.

```toml
[features]
memories = true

[memories]
use_memories = true
generate_memories = true
```

--------------------------------

### Define Weather Agent with Inlined Fetching Logic (TOML)

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/orchestration-workflow/orchestration-workflow.md

Defines the weather-agent in TOML format, including developer instructions for fetching data and invoking the weather-svg-creator skill. This pattern is used because Codex CLI subagents do not support preloaded skills.

```toml
# In agent definition (.codex/agents/weather-agent.toml)
name = "weather-agent"
description = "Fetches temperature from Open-Meteo, invokes skill."
developer_instructions = """
Step 1: Fetch from Open-Meteo API (use caller's unit preference, default Celsius)
Step 2: Invoke /weather-svg-creator skill
"""
```

--------------------------------

### Configure Codex as an MCP Server Consumer

Source: https://github.com/shanraisshan/codex-cli-best-practice/blob/main/best-practice/codex-mcp.md

Specify Codex as an MCP server within a consumer's configuration, defining its command and arguments. This is useful for applications that need to interact with Codex's MCP capabilities.

```json
{
  "mcpServers": {
    "codex": {
      "command": "codex",
      "args": ["mcp-server"]
    }
  }
}
```