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

> Understand the plugin.json manifest file, a key component for OpenAI platform integration. It acts as the single source of truth for plugin discovery, UI rendering, and runtime.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: documentation
- Published: 2026-06-24

---

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

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

```python
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`](https://github.com/openai/plugins/blob/main/plugin.json) data into the marketplace format.

```javascript
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`](https://github.com/openai/plugins/blob/main/plugin.json) to populate [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) with curated plugin listings.

## Summary

- **The [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and populate the plugin catalog.
- **Reference**: The authoritative specification lives 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).

## 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) serves as the **root manifest** defining the entire plugin's metadata and interface, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files are **application-specific manifests** referenced through the `apps` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json). The [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) files contain granular configuration for individual app components, whereas [`plugin.json`](https://github.com/openai/plugins/blob/main/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.