How the openai/plugins Repository Is Structured: A Complete Guide to Plugin Architecture

The openai/plugins repository uses a modular, self-describing architecture where each plugin resides in its own subdirectory under plugins/, anchored by a mandatory manifest at .codex-plugin/plugin.json, while top-level marketplace definitions in .agents/plugins/ enable automatic discovery and categorization by Codex.

The openai/plugins repository serves as the official curated registry for Codex-compatible plugin examples. Understanding its precise directory structure is essential for developers contributing new integrations or building tools that programmatically consume plugin metadata. The layout enforces strict conventions that allow the Codex runtime to discover, validate, and execute plugins independently.

Top-Level Directory Architecture

The repository root organizes content into three functional areas:

• README.md – Repository overview and featured plugin highlights
• .agents/ – Marketplace definitions and scaffolding tools
• plugins/ – Individual plugin packages, each in its own subdirectory

The .agents/ directory contains the discovery layer. Inside .agents/plugins/, two JSON files define the available plugin inventory:

• .agents/plugins/marketplace.json – Default marketplace listing all locally-available plugins
• .agents/plugins/api_marketplace.json – API-key-specific marketplace variant

Both files are generated automatically from the plugins/ directory contents. When you add a new plugin folder, the build process updates these manifests to include the plugin’s name, path, installation policy, authentication mode, and category.

Individual Plugin Package Structure

Every plugin lives under plugins/<plugin-name>/ and must follow a common convention. The structure supports both mandatory metadata and optional configuration files.

Required Files:

• plugins/<plugin-name>/.codex-plugin/plugin.json – The core manifest containing name, version, description, author, interface definition, and asset references

Optional Configuration Files:

• .app.json – Links the plugin to a native app connector used by Codex runtimes
• .mcp.json – Multi-Channel-Protocol definitions for advanced interactions

Optional Directories:

• assets/ – Icons, screenshots, and UI resources referenced by the manifest
• skills/ – Reusable skill modules exposing functions, agents, or YAML-defined workflows
• agents/ – YAML files describing Codex agents utilized by the plugin
• tests/ – Plugin-specific validation suites (JavaScript, Python, HTML, etc.)

Example: Gmail Plugin Structure

The Gmail plugin demonstrates the standard layout:

plugins/gmail/
├─ .codex-plugin/plugin.json        ← mandatory manifest
├─ .app.json                        ← app connector definition
├─ assets/
│   ├─ gmail.png
│   └─ gmail-small.svg
└─ README.md                        ← documentation

In plugins/gmail/.codex-plugin/plugin.json, the manifest defines the interface metadata that Codex uses to surface the plugin to users, including display names and icon paths.

Marketplace Metadata Configuration

The repository maintains two generated marketplace files that Codex consults for plugin discovery:

/.agents/plugins/marketplace.json lists every plugin with its metadata, file paths, and installation policies. This file drives the default user experience when browsing available tools.

/.agents/plugins/api_marketplace.json mirrors the default marketplace but applies when a user authenticates with an API key, potentially exposing different installation policies or plugin subsets.

These JSON files populate the category field for each plugin, enabling Codex to filter by domains such as Communication, Productivity, Developer Tools, Creativity, Finance, Education & Research, Data & Analytics, and Security.

Plugin Categories and Notable Examples

The repository organizes plugins into functional categories. Notable implementations include:

• Communication – gmail, slack, teams, outlook-email, zoom
• Productivity – linear, notion, clickup, monday-com, airtable
• Developer Tools – github, circleci, vercel, supabase, coderabbit
• Creativity – figma, canva, remotion, product-design
• Finance – stripe, public-equity-investing
• Security – codex-security

Each entry in the marketplace JSON includes the category field, allowing the Codex interface to group plugins by domain.

Developer Tooling and Scaffolding

The repository includes helper scripts to ensure new plugins conform to the required structure. Located at .agents/skills/plugin-creator/, this tooling assists with bootstrapping.

The script .agents/skills/plugin-creator/scripts/create_basic_plugin.py generates the mandatory directory structure and manifest templates. It references plugin-json-spec.md for schema validation, ensuring that generated plugin.json files include all required fields like name, version, description, and interface definitions.

Programmatic Access to Repository Data

Developers can navigate the openai/plugins repository structure programmatically to build tools, validators, or custom marketplaces.

Loading a Plugin Manifest

This Python function reads the standard manifest location for any plugin:

import json
from pathlib import Path

def load_manifest(plugin_name: str):
    """Read the .codex-plugin/plugin.json for a given plugin."""
    manifest_path = Path("plugins") / plugin_name / ".codex-plugin" / "plugin.json"
    with manifest_path.open() as f:
        return json.load(f)

gmail_manifest = load_manifest("gmail")
print(gmail_manifest["interface"]["displayName"])   # → Gmail

The code constructs the path plugins/<name>/.codex-plugin/plugin.json, consistent with the repository's naming convention, and extracts the display name from the interface metadata.

Listing Plugins by Category

To consume the marketplace data and group plugins by their assigned categories:

import json

def list_plugins_by_category(marketplace_path: str = ".agents/plugins/marketplace.json"):
    with open(marketplace_path) as f:
        data = json.load(f)
    categories = {}
    for entry in data["plugins"]:
        cat = entry["category"]
        categories.setdefault(cat, []).append(entry["name"])
    return categories

categories = list_plugins_by_category()
for cat, plugins in sorted(categories.items()):
    print(f"{cat}: {', '.join(plugins)}")

This script parses .agents/plugins/marketplace.json and aggregates plugin names under their respective category headings, producing output such as:

Communication: gmail, slack, teams, outlook-email, zoom
Productivity: linear, notion, clickup, monday-com, airtable

Summary

• The openai/plugins repository structures each plugin as an independent package under plugins/<plugin-name>/
• Every plugin must include a manifest at .codex-plugin/plugin.json describing its metadata and interface
• Marketplace discovery relies on auto-generated files at .agents/plugins/marketplace.json and api_marketplace.json
• Optional configurations include .app.json for native connectors and .mcp.json for protocol definitions
• Developer tooling at .agents/skills/plugin-creator/scripts/create_basic_plugin.py enforces the canonical structure when scaffolding new plugins
• Categories span Communication, Productivity, Developer Tools, Creativity, Finance, and Security, enabling filtered discovery in Codex

Frequently Asked Questions

What is the mandatory file required for every plugin in the openai/plugins repository?

Every plugin must contain a manifest file located at plugins/<plugin-name>/.codex-plugin/plugin.json. This JSON file defines the plugin's name, version, description, author, interface configuration, and asset references. Without this manifest, Codex cannot discover or load the plugin.

How does the repository handle plugin discovery and categorization?

Discovery happens through two JSON files in .agents/plugins/: marketplace.json for the default experience and api_marketplace.json for API-key-authenticated sessions. These files are auto-generated from the plugins/ directory and include category fields (such as Communication, Productivity, or Developer Tools) that enable Codex to filter and display plugins by domain.

Can I programmatically generate a new plugin that follows the repository's structure?

Yes. The repository includes a scaffolding script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py that generates the required directory layout and manifest template. This ensures new plugins conform to the structural requirements, including the mandatory .codex-plugin/plugin.json manifest and optional configuration files like .app.json.

What optional directories can a plugin include beyond the mandatory manifest?

Plugins may include several optional directories: assets/ for icons and screenshots, skills/ for reusable function modules, agents/ for YAML-defined Codex agents, and tests/ for validation suites. Additionally, plugins can specify app connectors via .app.json and advanced protocol handlers via .mcp.json at the plugin root.

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