How to Create a New Codex Plugin with a .codex-plugin/plugin.json Manifest

Create a directory under plugins/ containing a .codex-plugin/plugin.json manifest file that defines metadata, interface settings, and capabilities according to the Codex plugin schema.

The openai/plugins repository provides the reference implementation and JSON schema for building custom Codex plugins. At the core of every plugin is the .codex-plugin/plugin.json manifest file, which tells the Codex runtime how to discover, display, and execute your integration.

Required Directory Structure for Codex Plugins

Every Codex plugin lives in its own folder under the plugins/ directory. The runtime requires a specific layout to recognize and load your extension:

plugins/<my-plugin>/
    .codex-plugin/
        plugin.json
    assets/               # optional UI assets (icons, screenshots)

    skills/               # optional skill implementations

    .app.json             # optional app integration manifest

    .mcp.json             # optional MCP server descriptor

As documented in the repository's README.md, the .codex-plugin/plugin.json file is mandatory. All other files and directories are optional depending on whether your plugin requires custom assets, additional skills, or external app integrations.

Understanding the .codex-plugin/plugin.json Manifest Schema

The manifest must conform to the JSON schema documented in .agents/skills/plugin-creator/references/plugin-json-spec.md. This file defines the contract between your plugin and the Codex runtime.

Top-Level Metadata Fields

The root object of plugin.json requires several descriptive fields:

• name: A kebab-case identifier (e.g., my-plugin).
• version: A semantic version string (e.g., 1.0.0).
• description: A brief summary of the plugin's purpose.
• author: An object containing name, email, and url.
• homepage: The documentation URL for the plugin.
• repository: The source code URL.
• license: An SPDX license identifier (e.g., MIT).
• keywords: An array of search tags for marketplace discovery.
• apps: Relative path to the optional .app.json file (e.g., "./.app.json").

The Interface Configuration Object

The interface object contains the fields that the Codex UI reads to render your plugin. According to the spec, this includes:

• displayName: The human-readable name shown in the UI.
• shortDescription: A one-line subtitle.
• longDescription: Detailed markdown-supported description of capabilities.
• developerName: The entity responsible for the plugin.
• category: Classification such as Research or Productivity.
• capabilities: An array of feature flags.
• defaultPrompt: An array of suggested prompts (e.g., ["Find the most relevant highlights"]).
• composerIcon and logo: Relative paths to icon assets (e.g., "./assets/app-icon.png").
• websiteURL, privacyPolicyURL, termsOfServiceURL: Compliance and documentation links.

Real-World Manifest Examples from the openai/plugins Repository

The repository includes complete, production-ready plugins that demonstrate the schema implementation.

Readwise Plugin Configuration

Located at plugins/readwise/.codex-plugin/plugin.json, this manifest defines a Research-category plugin:

{
  "name": "readwise",
  "version": "1.0.1",
  "description": "The official app for Readwise and Reader.",
  "author": {
    "name": "Readwise Inc.",
    "url": "https://readwise.io"
  },
  "repository": "https://github.com/openai/plugins",
  "license": "MIT",
  "keywords": [],
  "apps": "./.app.json",
  "interface": {
    "displayName": "Readwise",
    "shortDescription": "The official app for Readwise and Reader.",
    "longDescription": "The official app for Readwise and Reader. \n\nThis app allows you to have Codex semantically search through all of your highlights, and any content saved to your Reader library.\n\nMore than that, it can do basically anything you can do in Reader! Triage your inbox, organize your library, catch up on your feed, and much more -- just ask :)",
    "developerName": "Readwise Inc.",
    "category": "Research",
    "capabilities": [],
    "defaultPrompt": [
      "Find the most relevant highlights in Readwise"
    ],
    "screenshots": [],
    "websiteURL": "https://readwise.io",
    "privacyPolicyURL": "https://readwise.io/privacy",
    "termsOfServiceURL": "https://readwise.io/tos",
    "composerIcon": "./assets/app-icon.png",
    "logo": "./assets/app-icon.png"
  },
  "homepage": "https://readwise.io"
}

Monday.com Plugin Configuration

The plugins/monday-com/.codex-plugin/plugin.json file shows a Productivity-category implementation:

{
  "name": "monday-com",
  "version": "1.0.1",
  "description": "A powerful MCP connector enabling AI agents to seamlessly interact with monday.com.",
  "author": {
    "url": "https://monday.com",
    "name": "Monday.com"
  },
  "homepage": "https://monday.com",
  "repository": "https://github.com/openai/plugins",
  "license": "MIT",
  "keywords": [],
  "apps": "./.app.json",
  "interface": {
    "displayName": "Monday.com",
    "shortDescription": "A powerful MCP connector enabling AI agents to seamlessly interact with monday.com.",
    "longDescription": "...",
    "category": "Productivity",
    "capabilities": [],
    "websiteURL": "https://monday.com",
    "privacyPolicyURL": "https://monday.com/l/privacy/privacy-policy/",
    "defaultPrompt": [
      "Check the marketing campaign status in monday.com"
    ],
    "screenshots": [],
    "composerIcon": "./assets/app-icon.png",
    "logo": "./assets/app-icon.png",
    "developerName": "Monday.com"
  }
}

Automating Plugin Creation with the Scaffold Script

Instead of manually creating directories and JSON files, use the provided scaffold utility at .agents/skills/plugin-creator/scripts/create_basic_plugin.py. This script automates the setup process by:

1. Normalizing and validating the plugin name.
2. Creating the directory tree including optional skills/ and assets/ folders.
3. Writing a placeholder .codex-plugin/plugin.json populated with [TODO] markers for required fields.
4. Optionally updating marketplace.json for discovery.

Execute the script from the repository root:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-plugin \
  --with-assets --with-skills --with-apps --with-marketplace

After execution, edit the generated plugins/my-plugin/.codex-plugin/plugin.json to replace the [TODO] placeholders with your actual metadata and interface configuration.

Handling Assets and Optional Configuration Files

If your plugin requires visual assets, create an assets/ directory within your plugin folder and store icons, logos, or screenshots there. Reference these files in plugin.json using relative paths like "./assets/app-icon.png". The Codex runtime bundles these assets and displays them in the plugin marketplace.

You may also include:

• .app.json: Defines app-specific integration settings.
• .mcp.json: Configures MCP (Model Context Protocol) server descriptors.
• skills/: Contains additional skill implementations referenced by your plugin.

Registering Your Plugin in marketplace.json

For the Codex runtime to discover your plugin, it must be registered in a marketplace.json file. This file controls the installPolicy, authPolicy, and category under which your plugin appears in the UI. The create_basic_plugin.py script can automatically insert this entry when you pass the --with-marketplace flag, or you can manually add the entry following the schema in the repository documentation.

Summary

• Create a directory under plugins/<name>/ with a .codex-plugin/ subdirectory containing the mandatory plugin.json file.
• Define the manifest according to the schema in .agents/skills/plugin-creator/references/plugin-json-spec.md, including top-level metadata and the interface object.
• Populate the interface fields such as displayName, category, defaultPrompt, and asset paths to control UI presentation.
• Store visual assets in an assets/ folder and reference them using relative paths like "./assets/app-icon.png".
• Use .agents/skills/plugin-creator/scripts/create_basic_plugin.py to scaffold new plugins automatically.
• Register the plugin in marketplace.json to enable discovery by the Codex runtime.

Frequently Asked Questions

What is the exact file path for the Codex plugin manifest?

The manifest must be located at plugins/<your-plugin-name>/.codex-plugin/plugin.json relative to the repository root. This specific path structure is required for the Codex runtime to identify the directory as a valid plugin package.

Which fields are mandatory in the plugin.json file?

Required top-level fields include name (kebab-case), version, description, author, license, and interface. Within the interface object, displayName, shortDescription, longDescription, and category are essential for proper rendering in the Codex UI.

Can I generate a Codex plugin scaffold automatically?

Yes. Run python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py <name> --with-assets --with-apps --with-marketplace to generate the complete directory structure, placeholder manifest, and marketplace entry. You must then edit the generated JSON to replace [TODO] placeholders with real values.

How do I reference icons and screenshots in the manifest?

Place image files in an assets/ folder within your plugin directory and reference them using relative paths such as "./assets/app-icon.png" in the composerIcon, logo, and screenshots fields of the interface object.

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