What Is the Purpose of the plugin.json Manifest File in OpenAI Plugins?

The plugin.json file serves as the core manifest that describes a Codex‑style plugin to the OpenAI platform, acting as the single source of truth for discovery, UI rendering, and runtime integration.

Each plugin in the openai/plugins repository relies on this JSON file to declare its identity, interface, and capabilities. Located in the hidden .codex-plugin/ directory of every plugin root, this manifest bridges the gap between the plugin code and the ChatGPT composer ecosystem.

Core Architectural Roles of plugin.json

The manifest fulfills four distinct architectural functions that enable the plugin framework to operate.

Metadata Store

At its foundation, plugin.json records the plugin’s identity metadata. This includes the name, version, and description fields that uniquely identify the package, alongside authoring data, licensing information, and discovery tags stored in the keywords array. For example, the Asana plugin defines these properties in plugins/asana/.codex-plugin/plugin.json.

Interface Definition

The interface object supplies UI‑level information consumed by the ChatGPT composer's plugin marketplace. This block contains the displayName, short and long descriptions, brand color specifications, icon paths, default prompts, and the capability list (such as Interactive or Write). These fields determine how the plugin appears visually and what actions users can perform within the interface.

Integration Hooks

Top‑level fields including apps, skills, hooks, and mcpServers serve as integration hooks that point to auxiliary manifests. The apps field references .app.json files, while other fields point to skill directories and hook configurations. The runtime loads these references to wire the plugin into the broader Codex ecosystem, as specified in .agents/skills/plugin-creator/references/plugin-json-spec.md.

Discovery and Marketplace Registration

The manifest drives plugin discovery through the marketplace generator. The keywords and category fields help users locate the plugin in the catalog, while the capabilities field informs the system which APIs the plugin may call. The marketplace generator reads this data to populate .agents/plugins/marketplace.json automatically.

File Location and Structure

Every plugin stores its manifest in a consistent location within the repository structure.

plugins/<plugin-name>/.codex-plugin/plugin.json

For instance, the Asana plugin manifest resides at plugins/asana/.codex-plugin/plugin.json. This hidden directory convention keeps configuration separate from implementation code while remaining accessible to the OpenAI runtime and build tools.

Reading plugin.json Programmatically

Developers can parse the manifest to extract plugin metadata or build tooling around the plugin ecosystem.

Node.js Implementation

Use the fs/promises module to asynchronously load the manifest:

import { readFile } from 'fs/promises';
import path from 'path';

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

// Example usage
loadManifest('plugins/asana')
  .then(manifest => console.log('Plugin name:', manifest.name))
  .catch(err => console.error('Failed to load manifest:', err));

Python Implementation

The pathlib module provides a clean approach for reading the JSON structure:

import json
from pathlib import Path

def load_manifest(plugin_root: str) -> dict:
    manifest_path = Path(plugin_root) / ".codex-plugin" / "plugin.json"
    with manifest_path.open() as f:
        return json.load(f)

# Example usage

manifest = load_manifest("plugins/asana")
print("Display name:", manifest["interface"]["displayName"])

Generating Marketplace Entries

You can programmatically generate marketplace catalog entries by transforming plugin.json data into the marketplace format.

import { readFileSync, writeFileSync } from 'fs';
import path from 'path';

const manifest = JSON.parse(
  readFileSync(path.resolve('plugins/asana/.codex-plugin/plugin.json'), 'utf-8')
);

const marketplace = {
  name: "openai-curated",
  interface: { displayName: "ChatGPT Official" },
  plugins: [
    {
      name: manifest.name,
      source: { source: "local", path: "./plugins/asana" },
      policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
      category: manifest.interface.category,
    },
  ],
};

writeFileSync('.agents/plugins/marketplace.json', JSON.stringify(marketplace, null, 2));

This pattern mirrors how the OpenAI platform consumes plugin.json to populate .agents/plugins/marketplace.json with curated plugin listings.

Summary

• The plugin.json file acts as the single source of truth for OpenAI plugin discovery and integration.
• Location: Each plugin stores its manifest in plugins/<name>/.codex-plugin/plugin.json.
• Key sections: Metadata fields (name, version), the interface object for UI rendering, and integration hooks (apps, skills, hooks, mcpServers).
• Consumption: The marketplace generator reads this file to build .agents/plugins/marketplace.json and populate the plugin catalog.
• Reference: The authoritative specification lives in .agents/skills/plugin-creator/references/plugin-json-spec.md.

Frequently Asked Questions

Where is plugin.json located in an OpenAI plugin?

The manifest resides in a hidden directory under each plugin's root: plugins/<plugin-name>/.codex-plugin/plugin.json. For example, the Asana plugin's manifest is located at plugins/asana/.codex-plugin/plugin.json.

What fields are required in plugin.json?

According to the specification in .agents/skills/plugin-creator/references/plugin-json-spec.md, the manifest must include identity fields (name, version, description) and an interface object containing displayName and category. Integration fields like apps or skills are required only if the plugin utilizes those specific capabilities.

How does plugin.json differ from .app.json?

While plugin.json serves as the root manifest defining the entire plugin's metadata and interface, .app.json files are application-specific manifests referenced through the apps field in plugin.json. The .app.json files contain granular configuration for individual app components, whereas plugin.json provides the high-level description required for marketplace discovery and runtime integration.

Can I read plugin.json programmatically?

Yes. Both Node.js and Python can parse the file using standard JSON libraries. The manifest uses standard JSON encoding (UTF-8), making it accessible to any language with JSON parsing capabilities. Refer to the code examples above for implementations using fs/promises in Node.js or pathlib in Python.

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