Codex Plugin Manifest Contract: Required Schema and File Structure

A Codex plugin manifest is a JSON file located at .codex-plugin/plugin.json that declares the plugin's identity, permissions, API specifications, and deliverables according to a strict schema enforced by the plugin-eval test suite.

The contract governs how the OpenAI Codex platform discovers, loads, and securely executes plugins from the openai/plugins repository. By standardizing metadata and capability declarations in a single JSON document, the manifest ensures consistent integration behavior and security boundaries across all Codex plugins.

File Location and Naming Convention

The manifest must reside in a hidden directory named .codex-plugin at the repository root, specifically at the path .codex-plugin/plugin.json. This convention allows Codex to recursively discover plugins by scanning for this specific file pattern across the filesystem.

Required Schema Fields

The contract defines eight mandatory top-level fields that every manifest must include to pass validation.

Core Identity Fields

• id: A unique, URL-safe string identifier (e.g., "zoom" or "minimal-plugin").
• name: Human-readable display name shown in the Codex UI.
• version: Semantic version string following standard conventions (e.g., "2.3.1").
• description: Concise summary of the plugin's functionality.
• author: Object containing at least name (string), optionally including url (string).
• type: Must be the literal string "codex-plugin" to identify the manifest format.

Capability and Security Fields

• permissions: Array of permission scope strings (e.g., "read:zoom_meetings", "write:zoom_meetings") defining the least-privilege access the plugin requires.
• apis: Object describing external API dependencies. Each key maps to an endpoint configuration, typically containing an openapi field pointing to an OpenAPI specification URL.

Optional Configuration Fields

Beyond the required schema, the contract supports optional fields for deliverables, branding, and metadata.

Deliverables and Artifacts

• primary_human_deliverable: String path to the main output file presented to users (e.g., "output/meeting_summary.pdf").
• human_deliverables: Array of additional file paths surfaced in the UI as supplementary outputs.
• support_artifacts: Array of objects describing auxiliary files (logs, data exports) with metadata such as user_visible_default.

Branding and Status

• logo or icons: String paths or URLs to visual assets for marketplace display.
• status: Publication state string indicating maturity ("alpha", "beta", or "stable").
• metadata: Free-form object for custom key-value pairs used by the plugin implementation.

Implementation Examples from openai/plugins

Minimal Plugin Fixture

The minimal-plugin fixture in the plugin-eval test suite demonstrates the minimal valid contract required to pass schema validation:

{
  "id": "minimal-plugin",
  "name": "Minimal Plugin",
  "version": "0.1.0",
  "description": "A minimal but valid Codex plugin manifest for testing.",
  "author": { "name": "OpenAI" },
  "type": "codex-plugin",
  "permissions": ["read:sample_data"],
  "apis": {
    "sample": {
      "openapi": "https://example.com/openapi.json"
    }
  }
}

Source: plugins/plugin-eval/fixtures/minimal-plugin/.codex-plugin/plugin.json

Zoom Plugin Production Manifest

The Zoom plugin illustrates a complete production implementation including optional deliverable and branding fields:

{
  "id": "zoom",
  "name": "Zoom",
  "version": "2.3.1",
  "description": "Connect Codex to Zoom meeting context, transcripts, recordings, and more.",
  "author": { "name": "Zoom", "url": "https://zoom.us" },
  "type": "codex-plugin",
  "permissions": [
    "read:zoom_meetings",
    "write:zoom_meetings",
    "read:zoom_recordings"
  ],
  "apis": {
    "rest": {
      "openapi": "https://api.zoom.us/v2/openapi.json"
    }
  },
  "primary_human_deliverable": "output/meeting_summary.pdf",
  "human_deliverables": ["output/meeting_transcript.txt"],
  "logo": "assets/logo.png"
}

Source: plugins/zoom/.codex-plugin/plugin.json

Schema Validation and Enforcement

The contract is enforced by the plugin-evaluator test suite defined in plugins/plugin-eval/tests/plugin-eval.test.js. This validator parses plugin.json to check for missing required fields, type mismatches, and invalid permission formats. The evaluator ensures that any plugin submitted to the Codex platform satisfies the manifest contract before execution is permitted.

Summary

• The Codex plugin manifest contract requires a JSON file at .codex-plugin/plugin.json containing required identity, permission, and API fields.
• Required fields include id, name, version, description, author, type (must be "codex-plugin"), permissions, and apis.
• Optional fields support user deliverables (primary_human_deliverable, human_deliverables), visual branding (logo), and lifecycle metadata (status).
• The schema is validated by the plugin-eval test suite to ensure security and consistency across the OpenAI plugins repository.

Frequently Asked Questions

Where must the plugin.json file be located?

Codex expects the manifest at the exact path .codex-plugin/plugin.json relative to the repository root. This hidden directory convention enables automatic discovery during the plugin loading process.

What is the difference between human_deliverables and support_artifacts?

Human deliverables are files explicitly presented to the user as primary outputs or supplementary documents, while support artifacts represent technical outputs like logs or raw data files that may be hidden by default but available for debugging or advanced use cases.

Is the apis field required if my plugin does not call external APIs?

Yes, the apis field is mandatory in the contract schema. If your plugin operates without external API calls, provide an empty object {} or define internal API schemas to satisfy the validation requirements in plugins/plugin-eval/tests/plugin-eval.test.js.

How does Codex validate the manifest schema?

The platform uses the plugin-evaluator to parse plugin.json, verifying that all required fields exist, conform to expected types (strings, arrays, objects), and that the type field exactly matches "codex-plugin" according to the contract defined in the source code.

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