Expected Path Format for the OpenAI Plugin Manifest File

TLDR: Every OpenAI Codex plugin must store its manifest file at <plugin-root>/plugin.json for the tooling to recognize and load it.

The openai/plugins repository enforces a strict file structure convention for plugin discovery. To ensure your Codex plugin is properly indexed and validated, you must place the metadata file at the exact expected path format for the OpenAI plugin manifest file that the discovery tools scan.

Canonical Manifest Location

According to the source code in the openai/plugins repository, the manifest file must live inside a hidden directory named .codex-plugin at the plugin's root. The complete relative path is:

plugin.json

This convention is documented across multiple files in the repository. The plugins/plugin-eval/README.md explicitly identifies .codex-plugin/plugin.json as the location for the Codex plugin manifest. Similarly, the reference implementation in .agents/skills/plugin-creator/references/plugin-json-spec.md generates scaffolding that creates this exact path structure.

Repository File References

Several key files in the openai/plugins repository confirm this path requirement:

• plugins/plugin-eval/README.md – Defines .codex-plugin/plugin.json as the canonical manifest location
• plugins/zoom/README.md – References the manifest using the relative path .codex-plugin/plugin.json
• .agents/skills/plugin-creator/references/plugin-json-spec.md – Contains scaffolding logic that creates the .codex-plugin directory and plugin.json file

Directory Structure Convention

All plugins in the repository follow a standardized layout. The .codex-plugin directory must sit at the root level of your plugin folder, sibling to other configuration files like .app.json.

plugins/
└─ zoom/
   ├─ .codex-plugin/
   │  └─ plugin.json        ← required manifest
   ├─ .app.json
   ├─ skills/
   └─ README.md

Placing plugin.json anywhere else—including the root directory or a differently named folder—will cause discovery and validation failures.

Loading the Manifest Programmatically

When building tools that interact with Codex plugins, you must construct the path using the .codex-plugin directory. The following Node.js example demonstrates how to correctly resolve and read the manifest:

import { readFileSync } from 'fs';
import { join } from 'path';

function loadPluginManifest(pluginRoot) {
  const manifestPath = join(pluginRoot, '.codex-plugin', 'plugin.json');
  const raw = readFileSync(manifestPath, 'utf-8');
  return JSON.parse(raw);
}

// Usage
const manifest = loadPluginManifest('./plugins/zoom');
console.log(manifest.name);   // → "zoom"

You can also reference this path in npm scripts for validation workflows:

{
  "scripts": {
    "validate-manifest": "node -e \"require('./scripts/validate')('./.codex-plugin/plugin.json')\""
  }
}

Summary

• The OpenAI plugin manifest must reside at <plugin-root>/plugin.json
• This path is hardcoded into the discovery tooling in the openai/plugins repository
• Files like plugins/plugin-eval/README.md and .agents/skills/plugin-creator/references/plugin-json-spec.md document this requirement
• Deviating from this path causes validation and discovery failures

Frequently Asked Questions

What is the exact file path for the OpenAI Codex plugin manifest?

The exact path is <plugin-root>/plugin.json, where <plugin-root> is the top-level directory of your plugin. This location is referenced in plugins/plugin-eval/README.md and required by all validation tools in the repository.

Can I place the manifest file in the plugin root directory instead?

No. Placing plugin.json directly in the plugin root without the .codex-plugin parent directory will cause discovery failures. The tooling specifically looks for the hidden .codex-plugin folder to identify valid plugin metadata.

Is the .codex-plugin folder name configurable?

No. The folder name .codex-plugin is a hardcoded convention in the openai/plugins repository. As shown in .agents/skills/plugin-creator/references/plugin-json-spec.md, scaffolding tools generate this exact directory name, and evaluators expect this specific path.

Where is the manifest path documented in the source code?

The path is documented in plugins/plugin-eval/README.md which describes .codex-plugin/plugin.json as the Codex plugin manifest location, and in plugins/zoom/README.md which links to the manifest using that relative path. The plugin creator references in .agents/skills/plugin-creator/references/plugin-json-spec.md also enforce this structure when generating new plugins.

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