# What Is the .codex-plugin/plugin.json Manifest in OpenAI Plugins?

> Understand the .codex-plugin/plugin.json manifest, a crucial file for OpenAI plugins. Learn how it structures metadata for discovery, validation, and marketplace display.

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

---

**The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file is the mandatory Codex plugin manifest that lives in a hidden `.codex-plugin` directory at the root of each plugin repository, containing structured metadata Codex uses to discover, validate, and display plugins in the marketplace.**

In the `openai/plugins` repository, every plugin must include this manifest file to be indexed by the platform. The JSON schema defines critical metadata ranging from human-readable descriptions to asset paths and permission scopes. When Codex scans a repository, it specifically looks for [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to determine if the package is a valid plugin and to extract the configuration needed for runtime wiring.

## Manifest Location and Schema

The manifest resides at [`plugin-root/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugin-root/.codex-plugin/plugin.json). This hidden directory convention keeps metadata separate from source code while remaining discoverable by the Codex indexer. The file must validate against the official Codex plugin schema to be accepted into the marketplace.

### Core Metadata Fields

The manifest stores essential plugin identity data:

| Field | Purpose |
|-------|---------|
| **`name`** | Human-readable plugin name displayed in the marketplace (e.g., "Zoom"). |
| **`version`** | Semantic version string (e.g., `"1.0.0"`). |
| **`description`** | Short summary shown to users browsing plugins. |
| **`author`** | Object containing `name` and optional `url` of the creator. |
| **`repository`** | URL of the source code repository. |
| **`homepage`** | Link to documentation or the plugin's landing page. |

### Assets and Permissions

Beyond basic metadata, the file declares visual assets and security scopes:

- **`logo`** / **`logoDark`**: Paths to logo assets, typically stored inside `.codex-plugin/assets`.
- **`composerIcon`**: Path to the icon used by the Codex UI composer.
- **`categories`**: Array of marketplace categories (e.g., `["Productivity"]`).
- **`tags`**: Free-form keywords for searchability.
- **`interface`**: Optional UI configuration including default prompts and widget settings.
- **`permissions`**: Declared API scopes required by the plugin (e.g., `"read:calendar"`).

## How Codex Uses the Manifest for Discovery

When the platform ingests a repository, it validates the presence and syntax of [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json). If the file is missing or malformed, the plugin is rejected from indexing. The **plugin-eval** evaluator, located at [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js), reads this file to verify JSON syntax and extract version data for runtime compatibility checks. The MCP server and various skill scripts also parse the manifest to resolve asset paths and permission sets before loading the plugin into the user interface.

## Accessing the Manifest Programmatically

Different components of the ecosystem read the manifest using language-specific implementations.

### Node.js Validation

The core evaluator uses a pattern similar to this to load and validate manifests:

```js
const path = require('path');
const fs = require('fs');

function loadManifest(pluginRoot) {
  const manifestPath = path.join(pluginRoot, '.codex-plugin', 'plugin.json');
  if (!fs.existsSync(manifestPath)) {
    throw new Error('Missing .codex-plugin/plugin.json');
  }
  const raw = fs.readFileSync(manifestPath, 'utf8');
  return JSON.parse(raw);
}

```

### Python Automation Scripts

Automation tooling outside the Node.js ecosystem often uses Python to read plugin metadata:

```python
from pathlib import Path
import json

def read_manifest(plugin_root: Path) -> dict:
    manifest_file = plugin_root / ".codex-plugin" / "plugin.json"
    if not manifest_file.is_file():
        raise FileNotFoundError("Manifest not found")
    return json.loads(manifest_file.read_text(encoding="utf-8"))

```

### React Frontend Components

Frontend widgets directly import the manifest to display plugin-specific branding. In `plugins/data-analytics`, the datascience artifact widget references the manifest like this:

```tsx
import pluginManifest from '../.codex-plugin/plugin.json';

export const WidgetHeader = () => (
  <header>
    <img src={pluginManifest.logo} alt={`${pluginManifest.name} logo`} />
    <h1>{pluginManifest.name}</h1>
    <p>{pluginManifest.description}</p>
  </header>
);

```

## Real-World Manifest Locations in the Repository

The `openai/plugins` repository demonstrates consistent manifest placement across diverse plugins:

- **[`plugins/zoom/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/.codex-plugin/plugin.json)**: Referenced by Zoom skill scripts for meeting integration metadata.
- **[`plugins/vercel/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/.codex-plugin/plugin.json)**: Listed in the Vercel README as part of the deployment plugin bundle.
- **[`plugins/temporal/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/temporal/.codex-plugin/plugin.json)**: Provides asset references including `logo` and `composerIcon`.
- **[`plugins/superpowers/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/superpowers/.codex-plugin/plugin.json)**: Used by server scripts to resolve runtime paths.
- **[`plugins/plugin-eval/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json)**: Loaded by [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) for self-validation and testing.
- **[`plugins/data-analytics/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/data-analytics/.codex-plugin/plugin.json)**: Imported directly in React components such as [`datascience-artifact-widget.jsx`](https://github.com/openai/plugins/blob/main/datascience-artifact-widget.jsx).

## Summary

- The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest is required for every plugin in the `openai/plugins` repository.
- It lives in a hidden `.codex-plugin` directory and must validate against the Codex JSON schema.
- Key fields include **name**, **version**, **description**, **author**, **logo**, **composerIcon**, **categories**, and **permissions**.
- The **plugin-eval** tool reads the manifest at [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js) to verify plugin validity.
- Manifests are consumed by Node.js evaluators, Python scripts, and React components like [`datascience-artifact-widget.jsx`](https://github.com/openai/plugins/blob/main/datascience-artifact-widget.jsx) to access metadata and assets.

## Frequently Asked Questions

### What happens if a plugin repository is missing the .codex-plugin/plugin.json file?

Codex will reject the repository from indexing and exclude it from the marketplace. The plugin-eval evaluator throws a `Missing .codex-plugin/plugin.json` error when attempting to load a plugin without this file, preventing runtime registration.

### What is the difference between the logo and composerIcon fields?

The **`logo`** field specifies the general plugin branding asset displayed in marketplace listings and documentation, while **`composerIcon`** points to a specific icon used within the Codex UI composer interface. Both paths typically reference files inside the `.codex-plugin/assets` directory.

### Where should assets referenced in the manifest be stored?

Asset files such as logos and icons should be placed in the `.codex-plugin/assets` folder, relative to the repository root. The manifest file references these using relative paths from its own location, ensuring the Codex indexer can resolve them during plugin packaging.

### How does the plugin-eval tool use the manifest during validation?

The plugin-eval tool, implemented in [`plugins/plugin-eval/src/evaluators/plugin.js`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/src/evaluators/plugin.js), loads [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to verify JSON syntax, extract the **version** for compatibility checks, and confirm required fields like **name** and **permissions** are present before the plugin is approved for deployment.