OpenAI Plugin Manifest Location: Finding plugin.json in the Monorepo

Every OpenAI plugin stores its manifest in a hidden .codex-plugin directory located at plugins/<plugin-name>/.codex-plugin/plugin.json according to the openai/plugins source code.

The openai/plugins repository organizes multiple plugins in a monorepo structure where each plugin requires a JSON manifest to define its identity and capabilities. Understanding the exact OpenAI plugin manifest location is essential for developers contributing new plugins or debugging existing integrations.

Standard Directory Structure for Manifests

In the openai/plugins repository, every individual plugin follows a strict directory convention documented in the root README.md. The manifest file, named plugin.json, resides in a hidden folder called .codex-plugin within each plugin's specific directory.

The complete file path follows this pattern:

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

For example, the Replit plugin's manifest is located at plugins/replit/.codex-plugin/plugin.json, while the Zoom plugin uses plugins/zoom/.codex-plugin/plugin.json. All plugins in the repository follow this consistent structure.

Manifest File Contents and Schema

The plugin.json file defines the plugin's identity, interface capabilities, and required configuration metadata. Below is the actual structure from the Replit manifest:

{
  "name": "replit",
  "interface": {
    "description": "Run code in a Replit container",
    "defaultPrompt": [
      {
        "role": "system",
        "content": "You are a helpful assistant that can execute code snippets in a Replit environment."
      }
    ]
  },
  "skills": ["run-code"],
  "hooks": [],
  "mcpServers": [],
  "apps": [],
  "metadata": {
    "author": "OpenAI",
    "version": "0.1.0"
  }
}

This configuration specifies the plugin's name, interface description, defaultPrompt for system instructions, and available skills.

Validation and Schema Specification

The repository includes automated tooling to validate these manifests against a formal schema. The specification defining required fields and data types is located at .agents/skills/plugin-creator/references/plugin-json-spec.md.

For runtime validation, the system uses plugins/plugin-eval/src/evaluators/plugin.js. This evaluator reads each plugin.json and checks for missing or malformed entries such as name, interface, and skills fields, ensuring all plugins meet the repository's standards before deployment.

Summary

• Every plugin manifest lives at plugins/<plugin-name>/.codex-plugin/plugin.json in the openai/plugins repository
• The hidden .codex-plugin directory contains the plugin.json configuration file
• Replit and Zoom plugins follow this pattern at plugins/replit/.codex-plugin/plugin.json and plugins/zoom/.codex-plugin/plugin.json respectively
• Schema validation is handled by plugins/plugin-eval/src/evaluators/plugin.js against the specification in .agents/skills/plugin-creator/references/plugin-json-spec.md

Frequently Asked Questions

Where is the OpenAI plugin manifest file located?

Each OpenAI plugin stores its manifest in a hidden .codex-plugin folder at plugins/<plugin-name>/.codex-plugin/plugin.json. For example, the Replit plugin manifest is located at plugins/replit/.codex-plugin/plugin.json and the Zoom plugin at plugins/zoom/.codex-plugin/plugin.json.

What is the schema specification for plugin.json?

The schema specification is defined in .agents/skills/plugin-creator/references/plugin-json-spec.md. This document outlines the required fields including name, interface, skills, and metadata that every OpenAI plugin manifest must contain.

How does OpenAI validate plugin manifests?

Validation is performed by the evaluator script at plugins/plugin-eval/src/evaluators/plugin.js, which checks each plugin.json file for the presence and correctness of required fields such as name, interface, and skills according to the repository standards.

Can I create a plugin without a .codex-plugin directory?

No, the .codex-plugin directory is mandatory as it houses the plugin.json manifest file that the evaluation tooling expects to find. Without this directory and file at the specified OpenAI plugin manifest location, the plugin will fail validation in the openai/plugins repository.

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