What Is the Required Manifest File for a Codex Plugin?

A Codex plugin must include a plugin.json file located inside a hidden .codex-plugin directory at the repository root to enable discovery, loading, and presentation within the Codex ecosystem.

The required manifest file for a Codex plugin serves as the single source of truth for the openai/plugins repository infrastructure. This JSON configuration defines everything from the plugin's identity and author information to its executable capabilities and UI assets. Without this specific file in the designated location, Codex cannot recognize or activate the repository as a valid plugin.

Required File Location and Naming Convention

Codex enforces a strict convention for manifest placement. The file must reside at .codex-plugin/plugin.json relative to the repository root. The .codex-plugin directory is hidden (prefixed with a dot), following Unix conventions for configuration directories.

This location is hardcoded into the Codex plugin discovery system. When scanning a repository, Codex specifically looks for this path to differentiate plugin packages from standard codebases. Placing the manifest anywhere else, or naming it differently, results in the plugin being ignored during the indexing process.

Required Fields in plugin.json

The manifest follows a strict JSON schema that declares the plugin's structure and runtime behavior. According to the openai/plugins source code, the top-level object must contain several mandatory sections.

Core Metadata

Every manifest must define basic identity fields:

• name: The machine-readable plugin identifier (lowercase, no spaces).
• version: Semantic versioning string (e.g., "1.0.0").
• author: Object containing name and url properties.
• description: Human-readable summary of functionality.
• homepage: URL to the plugin's documentation or landing page.
• license: SPDX license identifier (e.g., "MIT").
• repository: URL to the source code repository.
• keywords: Array of searchable tags for discovery.

Interface Configuration

The interface object defines how the plugin appears in the Codex UI and what operations it supports:

• displayName: The user-facing name shown in interfaces.
• logo: Relative path to the plugin's icon (e.g., "./assets/logo.jpg").
• **brandColor``: Hex color code for theming (e.g., "#0B5CFF"`).
• category: Classification for organization (e.g., "Communication").
• defaultPrompt: Array of suggested prompt strings to guide users.
• capabilities: Array declaring permissions: "Read", "Write", and/or "Interactive".

App and Skill References

The manifest must declare where Codex can find the executable components:

• apps: String path to an .app.json file that lists sub-applications (e.g., "./.app.json").
• skills: String path to the directory containing skill scripts (e.g., "./skills/").

Complete Manifest Example

The Zoom plugin in the openai/plugins repository demonstrates the full implementation. The .codex-plugin/plugin.json file declares all required fields with proper nesting:

{
  "apps": "./.app.json",
  "author": { 
    "name": "Zoom", 
    "url": "https://github.com/zoom" 
  },
  "description": "Smart meeting insights from Zoom",
  "homepage": "https://developers.zoom.us/",
  "interface": {
    "brandColor": "#0B5CFF",
    "capabilities": ["Interactive", "Read", "Write"],
    "category": "Communication",
    "defaultPrompt": [
      "Search my recent Zoom meetings for the discussion about pricing.",
      "Run /plan-zoom-product for a Zoom integration idea."
    ],
    "displayName": "Zoom",
    "logo": "./assets/logo.jpg"
  },
  "keywords": ["zoom", "codex-plugin", "connector"],
  "license": "MIT",
  "name": "zoom",
  "repository": "https://github.com/zoom/zoom-plugin-codex",
  "skills": "./skills/",
  "version": "1.0.0"
}

Supporting Files Referenced by the Manifest

The plugin.json file points to several auxiliary files that complete the plugin structure:

• .app.json: Located at the path specified in the apps field, this file enumerates individual applications or sub-plugins provided by the package.
• skills/ directory: The folder specified in the skills field contains the executable scripts that implement the plugin's logic.
• README.md: While not referenced in the manifest, this file provides human-readable documentation expected at the repository root.

Summary

• A valid Codex plugin requires plugin.json inside a .codex-plugin directory at the repository root.
• The manifest must declare core metadata (name, version, author), interface properties (logo, capabilities, brand color), and paths to apps and skills.
• Capabilities are declared as an array including "Read", "Write", and/or "Interactive" permissions.
• The apps field points to .app.json, while skills points to the directory containing executable scripts.

Frequently Asked Questions

What is the exact filename and location for a Codex plugin manifest?

The file must be named exactly plugin.json and located at .codex-plugin/plugin.json relative to the repository root. The .codex-plugin directory is hidden (dot-prefixed) and must exist at the top level of the repository. Codex discovery systems specifically scan for this path to identify valid plugins.

What capabilities can be declared in the interface object?

The capabilities array accepts three string values: "Read" for data access operations, "Write" for data modification operations, and "Interactive" for real-time user engagement features. These declarations control what actions Codex permits the plugin to perform and determine the UI presentation in the interface.

How do I reference multiple apps in a single plugin?

The apps field in plugin.json points to a single .app.json file (not a directory). This JSON file contains an array of app definitions, allowing one plugin package to expose multiple sub-applications or integrations. Each entry in .app.json can define its own routes, permissions, and entry points.

Is the .codex-plugin directory required to be hidden?

Yes, the .codex-plugin directory must use the dot-prefix convention (.codex-plugin rather than codex-plugin). This follows Unix hidden directory standards and is explicitly required by the Codex plugin loader. The leading dot signals to both the file system and the discovery mechanism that this directory contains configuration rather than user-facing content.

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