OpenAI Codex Plugin Manifest File Structure: Complete Schema Guide

The plugin manifest is a JSON file located at plugins/<plugin-name>/.codex-plugin/plugin.json that defines metadata, capabilities, and UI presentation for Codex plugins using a structured schema with required fields like name, version, skills, and an interface object.

The openai/plugins repository establishes a standardized manifest format that powers the Codex plugin ecosystem. This JSON configuration serves as the contract between plugin developers and the marketplace, controlling everything from discovery to execution permissions while following the Codex Plugin Manifest Specification.

Plugin Manifest Location and File Path

Every Codex plugin must include a manifest file at a specific location within the repository structure. According to the source code organization, the file resides at:

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

This convention ensures consistent discovery across all plugins in the openai/plugins repository. For example, the Zotero plugin stores its manifest at plugins/zotero/.codex-plugin/plugin.json, while the Fyxer plugin uses plugins/fyxer/.codex-plugin/plugin.json.

Core Plugin Manifest Schema

The manifest follows the Codex Plugin Manifest Specification, which requires specific top-level fields to validate correctly. Missing required fields causes the plugin to be rejected during the validation process.

Required Metadata Fields

The root object must include these mandatory fields:

• name: Unique identifier for the plugin (e.g., "zotero")
• version: Semantic version string (e.g., "0.1.2")
• description: Short text displayed in the marketplace listings
• homepage: URL to the plugin's home page
• repository: Source code repository URL
• license: SPDX license identifier (e.g., "MIT")
• keywords: Array of search tags (e.g., ["zotero", "citations"])
• skills: Relative path to the folder containing skill definitions (e.g., "./skills/")

Author Configuration

The author field requires an object containing:

• name: Developer or organization name
• email: Optional contact address
• url: Optional website link

Optional App Integration

Plugins may include an apps field that specifies a relative path to an .app.json file defining an MCP-compatible application. The Fyxer plugin demonstrates this pattern with "apps": "./.app.json", enabling extended functionality beyond standard skills.

The Interface Object Structure

The interface object controls how the plugin appears to end users in the Codex marketplace and UI.

Display and Branding Fields

• displayName: Human-readable name shown in the UI
• shortDescription: One-line tagline for quick identification
• longDescription: Full description text for detailed marketplace listings
• developerName: Company or individual author name
• category: Marketplace classification (e.g., Education & Research, Productivity)
• brandColor: Optional hex color code for UI theming

Capability Definitions

The capabilities array defines execution permissions using specific string values:

• Read: Access to read operations
• Write: Permission to modify data
• Interactive: Support for interactive sessions

Note that some plugins, like the read-only Fyxer implementation, may omit this array entirely.

Legal and Asset References

• websiteURL: Link to external plugin documentation
• privacyPolicyURL: Required legal disclosure link
• termsOfServiceURL: Terms of service hyperlink
• composerIcon: Relative path to composer icon asset
• logo: Path to logo image file
• screenshots: Optional array of image URLs for marketplace gallery
• defaultPrompt: Array of suggested starter prompts for users

Plugin Manifest File Examples

These implementations from the openai/plugins repository demonstrate the schema in practice.

Minimal Required Configuration

This example shows only the mandatory fields for a basic plugin:

{
  "name": "my-plugin",
  "version": "0.0.1",
  "description": "Brief description",
  "author": { "name": "My Company", "url": "https://mycompany.com" },
  "homepage": "https://mycompany.com",
  "repository": "https://github.com/mycompany/plugins",
  "license": "MIT",
  "keywords": ["example", "plugin"],
  "skills": "./skills/",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "One-line tagline",
    "longDescription": "Long description that appears in the marketplace.",
    "developerName": "My Company",
    "category": "Productivity",
    "capabilities": ["Read"],
    "websiteURL": "https://mycompany.com",
    "privacyPolicyURL": "https://mycompany.com/privacy",
    "termsOfServiceURL": "https://mycompany.com/terms",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "defaultPrompt": ["@MyPlugin do something"]
  }
}

Full Implementation with App Integration

This configuration from the Fyxer plugin includes the optional apps field linking to an MCP-compatible application descriptor:

{
  "name": "awesome-app",
  "version": "1.2.0",
  "description": "An app-style plugin",
  "author": { "name": "Awesome Inc.", "url": "https://awesome.inc" },
  "apps": "./.app.json",
  "interface": {
    "displayName": "Awesome App",
    "shortDescription": "Automated workflow assistant",
    "longDescription": "Full marketplace description here.",
    "developerName": "Awesome Inc.",
    "category": "Productivity",
    "websiteURL": "https://awesome.inc",
    "privacyPolicyURL": "https://awesome.inc/privacy",
    "termsOfServiceURL": "https://awesome.inc/terms",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "defaultPrompt": ["@AwesomeApp analyze my data"],
    "brandColor": "#FF5733"
  }
}

Validation and Schema Compliance

The manifest must validate against OpenAI's Codex Plugin Manifest Specification. The repository enforces this schema during submission review, rejecting any plugin with missing required fields or incorrect data types. Both the Zotero and Fyxer implementations adhere to this stable contract, confirming the consistency requirements across all plugins in the ecosystem.

Summary

• The plugin manifest resides at plugins/<plugin-name>/.codex-plugin/plugin.json and serves as the canonical configuration for Codex plugins.
• Required fields include name, version, description, author, homepage, repository, license, keywords, and skills.
• The interface object controls marketplace presentation through displayName, longDescription, category, and capabilities arrays.
• Optional apps fields enable MCP-compatible application integration by referencing .app.json files.
• Real-world examples in plugins/zotero/.codex-plugin/plugin.json and plugins/fyxer/.codex-plugin/plugin.json demonstrate the complete schema implementation.

Frequently Asked Questions

What is the required file path for a Codex plugin manifest?

The manifest must be located at plugins/<plugin-name>/.codex-plugin/plugin.json relative to the repository root. This specific path structure enables the Codex system to discover and validate plugins automatically.

What capabilities can a plugin declare in its manifest structure?

Plugins declare permissions through the capabilities array within the interface object, supporting Read for data access, Write for modification rights, and Interactive for session-based interactions. Some plugins, like Fyxer, omit this field when operating in read-only mode.

How does the apps field extend the plugin manifest structure?

The optional apps field specifies a relative path to an .app.json file, enabling MCP-compatible applications that extend beyond standard skill definitions. This allows plugins to define complex application behaviors while maintaining the core manifest structure.

What happens if required fields are missing from the plugin manifest?

The Codex plugin validation process rejects manifests missing required fields such as name, version, or interface. The schema defined by OpenAI's Codex Plugin Manifest Specification enforces strict compliance to ensure marketplace consistency and proper plugin execution.

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