Where Should the Plugin Manifest File Be Located in an OpenAI Plugins Repository?

The plugin manifest file must be placed in a hidden folder named .codex-plugin at the root of each plugin's directory, with the exact filename plugin.json, forming the required path <plugin-root>/.codex-plugin/plugin.json.

In the OpenAI plugins repository, every Codex plugin must declare its metadata, capabilities, and entry points through a standardized manifest file. According to the repository's conventions and validation logic, this critical configuration file has a strictly enforced location that tooling expects to find when loading and evaluating plugins.

Required Plugin Manifest File Location

The plugin manifest file location is non-negotiable and must follow the exact path: .codex-plugin/plugin.json relative to the plugin's root directory.

As implemented in the openai/plugins repository, the plugin-eval evaluator explicitly searches for this file at <plugin-root>/.codex-plugin/plugin.json. In plugins/plugin-eval/src/evaluators/plugin.js (lines 26-28), the validation code constructs the path by joining the plugin root with .codex-plugin and plugin.json, then reads the file to parse the plugin's configuration.

The top-level README.md confirms this requirement, documenting the manifest as the entry point that must live at .codex-plugin/plugin.json. This convention ensures that automated tooling, CI pipelines, and the evaluation framework can consistently discover plugin metadata without configuration overhead.

Directory Structure and Naming Conventions

The Hidden .codex-plugin Directory

The .codex-plugin folder is a hidden directory (prefixed with a dot) that sits at the root of your plugin's folder. This directory contains the plugin.json file and serves as the standardized container for plugin metadata.

When creating a new plugin, you must create this directory at the same level as your source code, documentation, and other plugin assets. The naming is strict—deviating from .codex-plugin will cause the evaluator to fail to recognize your plugin.

Example: Vercel Plugin Implementation

The Vercel plugin in the repository demonstrates the correct structure. Its manifest lives at plugins/vercel/.codex-plugin/plugin.json, as documented in the Architecture section of the Vercel plugin's README.md.

This placement follows the repository-wide standard where each plugin maintains its own .codex-plugin subdirectory containing the single plugin.json entry point. The path plugins/vercel/.codex-plugin/plugin.json serves as the living reference implementation for all new plugins.

How the Manifest Is Discovered Programmatically

The evaluation framework programmatically resolves the plugin manifest file location using Node.js path utilities. The code explicitly joins the plugin root directory with the .codex-plugin folder and plugin.json filename.

const path = require('path');
const fs = require('fs/promises');

async function loadManifest(pluginRoot) {
  const manifestPath = path.join(pluginRoot, '.codex-plugin', 'plugin.json');
  const raw = await fs.readFile(manifestPath, 'utf8');
  return JSON.parse(raw);
}

// Example usage loading the Vercel plugin manifest
loadManifest('./plugins/vercel')
  .then(manifest => console.log('Loaded manifest:', manifest.name));

This implementation in plugins/plugin-eval/src/evaluators/plugin.js shows that the system performs no recursive searching or alternative path checking—it expects the manifest exactly at this location.

Creating a Valid Plugin Manifest

Place the following JSON structure at <your-plugin>/.codex-plugin/plugin.json to define your plugin's metadata:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "My first Codex plugin",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Demo plugin for Codex",
    "longDescription": "A simple example showing where the manifest lives.",
    "developerName": "Your Name",
    "category": "Utilities",
    "capabilities": ["Interactive"]
  },
  "skills": "./skills/",
  "apps": "./.app.json"
}

This file must be valid JSON and include required fields such as name, version, description, and interface. The skills and apps paths are relative to the plugin root, not the .codex-plugin folder.

Summary

• The plugin manifest file location is strictly enforced at <plugin-root>/.codex-plugin/plugin.json.
• The .codex-plugin folder must be a hidden directory (dot-prefixed) located at the root of each plugin.
• The validation logic in plugins/plugin-eval/src/evaluators/plugin.js hardcodes this path expectation and will fail to load plugins with manifests placed elsewhere.
• Every plugin in the repository, including the reference Vercel implementation, follows this convention for consistency and tooling compatibility.

Frequently Asked Questions

Can I place the manifest file in a different directory?

No. The evaluation framework specifically looks for the file at .codex-plugin/plugin.json relative to the plugin root. Placing the manifest elsewhere will cause the plugin loader to fail, as the path is hardcoded in the evaluator logic at plugins/plugin-eval/src/evaluators/plugin.js.

Is the .codex-plugin folder required to be hidden?

Yes, the folder name must begin with a dot (.codex-plugin), making it a hidden directory on Unix-like systems. This naming convention is part of the required path structure that the tooling expects when resolving plugin metadata.

What happens if the evaluator cannot find the manifest?

If the file is missing at the expected path, the plugin evaluation will fail. The code attempts to read plugin.json from the .codex-plugin directory and throws an error or returns a validation failure if the file does not exist at that specific location.

Does every plugin need its own manifest file?

Yes, every individual plugin in the repository must contain its own .codex-plugin/plugin.json file. This requirement ensures that each plugin declares its own metadata, capabilities, and skill locations independently, allowing the evaluation framework to process plugins individually.

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