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

> Discover the correct location for your OpenAI plugin manifest file within a repository. Learn to place plugin.json in the .codex-plugin folder at the root.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: best-practices
- Published: 2026-07-12

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json), then reads the file to parse the plugin's configuration.

The top-level [`README.md`](https://github.com/openai/plugins/blob/main/README.md) confirms this requirement, documenting the manifest as the entry point that must live at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json), as documented in the Architecture section of the Vercel plugin's [`README.md`](https://github.com/openai/plugins/blob/main/README.md).

This placement follows the repository-wide standard where each plugin maintains its own `.codex-plugin` subdirectory containing the single [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) entry point. The path [`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) filename.

```javascript
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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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.