# What Is the Required Manifest File for a Codex Plugin?

> Discover the essential plugin.json manifest file required for your Codex plugin. Learn how to enable discovery, loading, and presentation in the Codex ecosystem.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-12

---

**A Codex plugin must include a [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file declares all required fields with proper nesting:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/plugin.json) file points to several auxiliary files that complete the plugin structure:

- **[`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) and located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) points to a single [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.