.codex-plugin/plugin.json Schema: Complete Reference for OpenAI Codex Plugins

The .codex-plugin/plugin.json file is a JSON manifest that defines a Codex plugin's metadata, UI configuration, and asset paths, using a strict schema with required fields like name, version, skills, and a nested interface object.

The .codex-plugin/plugin.json schema serves as the single source of truth for the Codex runtime in the openai/plugins repository. This manifest tells the system how to load skill definitions, render UI components in the composer, and display the plugin in the marketplace.

Top-Level Schema Fields

Every plugin manifest must reside at .codex-plugin/plugin.json relative to the plugin root. The schema consists of string fields, objects, and arrays that configure both runtime behavior and presentation.

Identification and Metadata

These fields define the plugin's identity and discoverability:

• name (string, required): Machine-readable identifier (e.g., "hex", "factset").
• version (string, required): Semantic version following standard versioning (e.g., "0.1.0").
• description (string, required): Brief human-readable summary of functionality.
• author (object, required): Contains name (string, required) and optional url (string) pointing to the author's website.
• homepage (string, required): URL to the plugin's public landing page.
• repository (string, required): URL to the source repository (typically the openai/plugins repo).
• license (string, required): SPDX license identifier (e.g., "MIT", "Proprietary").
• keywords (array<string>, optional): Tags for search and categorization (e.g., ["analytics", "data"]).

Asset Paths

These fields point to the plugin's executable components:

• skills (string, required): Relative path to the directory containing skill definitions (e.g., "./skills/").
• apps (string, required): Relative path to the .app.json file that defines UI components (e.g., "./.app.json").

Interface Object Schema

The interface object (required) contains all UI-related metadata that the Codex runtime uses to render the plugin in the composer and marketplace.

Display Properties

• displayName (string, required): Human-readable name shown in the UI.
• shortDescription (string, required): One-line description for plugin listings.
• longDescription (string, required): Full description displayed on detail pages.
• developerName (string, required): Name of the organization that built the plugin.
• category (string, required): High-level classification (e.g., "Data & Analytics", "Productivity").
• brandColor (string, required): Hex color code for UI accents (e.g., "#182A4D").

Interaction Configuration

• capabilities (array<string>, required): Supported interaction modes. Common values include "Read", "Write", and "Interactive". May be empty.
• defaultPrompt (string or array<string>, required): Default prompt(s) suggested to users to invoke the plugin. As demonstrated in plugins/factset/.codex-plugin/plugin.json, this can be an array of multiple example prompts.

Visual Assets

• composerIcon (string, required): Relative path to the 32px icon displayed in the composer.
• logo (string, required): Relative path to the plugin logo used in the marketplace.
• screenshots (array<string>, optional): Array of paths to screenshot images for marketplace display.

Legal and Support Links

• websiteURL (string, required): Link to the plugin's public website.
• privacyPolicyURL (string, optional): Link to the privacy policy.
• termsOfServiceURL (string, optional): Link to the terms of service.

Required vs Optional Fields

Understanding the strict requirements prevents validation errors during plugin loading.

Required fields (must appear for valid plugin loading):

• name, version, description, author.name
• homepage, repository, license
• skills, apps
• interface (and all its sub-fields except privacyPolicyURL, termsOfServiceURL, and screenshots)

Optional fields (may be omitted, falling back to defaults):

• author.url, keywords
• interface.privacyPolicyURL, interface.termsOfServiceURL, interface.screenshots

Complete Example Manifest

Below is a minimal yet valid plugin.json that satisfies all schema requirements:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "Brief description of what the plugin does.",
  "author": { "name": "My Company" },
  "homepage": "https://mycompany.com",
  "repository": "https://github.com/openai/plugins/tree/main/plugins/my-plugin",
  "license": "MIT",
  "keywords": [],
  "skills": "./skills/",
  "apps": "./.app.json",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "One-line summary.",
    "longDescription": "Longer description used in the marketplace.",
    "developerName": "My Company",
    "category": "Productivity",
    "capabilities": ["Read", "Write"],
    "brandColor": "#123456",
    "defaultPrompt": "Ask me to do something with My Plugin.",
    "composerIcon": "./assets/icon.png",
    "logo": "./assets/logo.png",
    "websiteURL": "https://mycompany.com",
    "privacyPolicyURL": "https://mycompany.com/privacy",
    "termsOfServiceURL": "https://mycompany.com/terms",
    "screenshots": []
  }
}

Replace placeholder paths with actual files relative to your plugin directory.

Reference Implementations

The openai/plugins repository contains concrete implementations that demonstrate the full schema:

• Hex: plugins/hex/.codex-plugin/plugin.json demonstrates optional UI links and complete interface configuration.
• FactSet: plugins/factset/.codex-plugin/plugin.json shows the defaultPrompt field as an array and empty capabilities.
• Docket: plugins/docket/.codex-plugin/plugin.json provides another example of the full schema structure.
• Help-Scout: plugins/help-scout/.codex-plugin/plugin.json illustrates standard field usage.

Summary

• The .codex-plugin/plugin.json file is the mandatory manifest that configures every Codex plugin in the openai/plugins repository.
• Required fields include name, version, skills, apps, and the complete interface object (minus optional URL fields).
• Optional fields like keywords, screenshots, and legal URLs enhance discoverability and compliance but are not mandatory for loading.
• The interface object controls all UI rendering, including icons, colors, prompts, and capabilities.
• Real-world examples in plugins/hex/.codex-plugin/plugin.json and plugins/factset/.codex-plugin/plugin.json serve as authoritative references.

Frequently Asked Questions

What is the .codex-plugin/plugin.json file used for?

The file serves as the manifest that tells the Codex runtime how to load and display a plugin. It defines the plugin's identity, points to skill definitions and UI components, and configures how the plugin appears in the composer and marketplace.

Is the author.url field required?

No, only author.name is required within the author object. The author.url field is optional and can be omitted if the author does not have a specific website to reference.

Can defaultPrompt be an array instead of a string?

Yes, according to the schema implementation in plugins/factset/.codex-plugin/plugin.json, the defaultPrompt field accepts either a single string or an array of strings to provide multiple example prompts for users.

Where should the plugin.json file be located?

The file must reside at the path .codex-plugin/plugin.json relative to the plugin root directory. This specific location is hardcoded in the Codex runtime as the entry point for plugin discovery and loading.

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