# Expected Path Format for the OpenAI Plugin Manifest File

> Learn the required path format for your OpenAI plugin manifest file. Discover where to place plugin.json for proper loading and recognition by the OpenAI tooling.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: api-reference
- Published: 2026-07-05

---

**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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md) explicitly identifies [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md)** – Defines [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) as the canonical manifest location
- **[`plugins/zoom/README.md`](https://github.com/openai/plugins/blob/main/plugins/zoom/README.md)** – References the manifest using the relative path [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)
- **[`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md)** – Contains scaffolding logic that creates the `.codex-plugin` directory and [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.app.json).

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

```

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

```javascript
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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md) and [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md) which describes [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) as the Codex plugin manifest location, and in [`plugins/zoom/README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) also enforce this structure when generating new plugins.