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

The .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 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. 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. 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, 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:

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:

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:

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: Referenced by Zoom skill scripts for meeting integration metadata.
• plugins/vercel/.codex-plugin/plugin.json: Listed in the Vercel README as part of the deployment plugin bundle.
• plugins/temporal/.codex-plugin/plugin.json: Provides asset references including logo and composerIcon.
• plugins/superpowers/.codex-plugin/plugin.json: Used by server scripts to resolve runtime paths.
• plugins/plugin-eval/.codex-plugin/plugin.json: Loaded by plugins/plugin-eval/src/evaluators/plugin.js for self-validation and testing.
• plugins/data-analytics/.codex-plugin/plugin.json: Imported directly in React components such as datascience-artifact-widget.jsx.

Summary

• The .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 to verify plugin validity.
• Manifests are consumed by Node.js evaluators, Python scripts, and React components like 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, loads .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.

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