OpenAI Plugins Repository Structure: A Complete Guide to the Directory Layout

The openai/plugins repository follows a modular architecture where each plugin resides in its own subdirectory under plugins/ with a mandatory JSON manifest, while marketplace definitions in .agents/plugins/ enable automatic discovery and categorization by the Codex runtime.

The openai/plugins repository hosts the official reference collection for Codex plugin examples, implementing a standardized filesystem layout that separates configuration, assets, and executable code into predictable locations. This design allows each plugin to function as an independent package while maintaining consistency across categories ranging from Communication to Security.

Top-Level Directory Layout

The repository root contains three primary components that govern plugin discovery and documentation.

Repository documentation resides in README.md, which introduces the repository’s intent and highlights featured integrations.

Marketplace definitions live inside the .agents/ directory. Specifically, /.agents/plugins/marketplace.json lists every locally available plugin with its installation policy, authentication mode, and category, while /.agents/plugins/api_marketplace.json provides an alternative marketplace configuration for API-key-based authentication. Both files auto-generate from the contents of the plugins/ directory, ensuring the marketplace stays synchronized with the filesystem.

Plugin packages occupy the plugins/ directory, with each subfolder representing a complete, self-contained integration such as gmail/, slack/, or github/.

Individual Plugin Structure

Every plugin directory under plugins/<plugin-name>/ follows a mandatory convention for the manifest and supports several optional configuration layers.

Required Manifest

Each plugin must contain a manifest at plugins/<plugin-name>/.codex-plugin/plugin.json. This JSON file defines core metadata including the plugin name, version, description, author, and interface specifications required by the Codex runtime.

Optional Configuration Files

Beyond the manifest, plugins may include:

• .app.json – Links the plugin to a native app connector used by Codex runtimes.
• .mcp.json – Contains Multi-Channel-Protocol definitions for advanced interactions.
• assets/ – Stores UI resources such as icons and screenshots referenced by the manifest.
• skills/ – Houses reusable skill modules exposing functions, agents, or YAML-defined workflows.
• agents/ – Contains YAML files describing Codex agents utilized by the plugin.
• tests/ – Hosts plugin-specific test suites in JavaScript, Python, HTML, or other languages.

For example, the Gmail plugin demonstrates this structure with its manifest at plugins/gmail/.codex-plugin/plugin.json, an app connector at plugins/gmail/.app.json, and UI assets in plugins/gmail/assets/.

Plugin Categories

The repository organizes plugins into functional categories declared in marketplace.json. These 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
• Education & Research – zotero, life-science-research, ngs-analysis
• Security – codex-security

Each entry in the marketplace JSON includes a category field enabling Codex to filter plugins by domain.

Developer Tooling and Scaffolding

The repository includes automation utilities under /.agents/skills/plugin-creator/. The create_basic_plugin.py script assists contributors in scaffolding new plugins that conform to the required layout, while plugin-json-spec.md documents the manifest schema. These tools ensure new submissions automatically appear in the marketplace JSON files upon generation.

Working with the Repository Programmatically

Consumers can interact with the openai/plugins repository structure using standard filesystem and JSON parsing utilities.

Loading a Plugin Manifest

The following Python function reads the mandatory plugin.json manifest for any given plugin name:

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

This approach leverages the predictable repository structure to access metadata without hardcoding full paths.

Enumerating Plugins by Category

To analyze the marketplace configuration programmatically:

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)}")

Executing this script outputs a grouped view of the repository contents, such as listing all Communication or Productivity tools available in the marketplace.

Summary

• The openai/plugins repository uses a modular structure where each plugin occupies an independent subdirectory under plugins/.
• Every plugin requires a manifest at .codex-plugin/plugin.json and may optionally include .app.json, .mcp.json, assets, skills, agents, and tests.
• Marketplace metadata in /.agents/plugins/marketplace.json and api_marketplace.json auto-generates from the plugins/ directory contents.
• Helper scripts in /.agents/skills/plugin-creator/ provide scaffolding tools for new plugin development.
• The repository categorizes plugins into domains like Communication, Productivity, and Developer Tools for easy discovery by the Codex runtime.

Frequently Asked Questions

Where is the main plugin manifest located in the openai/plugins repository?

Each plugin stores its core metadata in a JSON manifest located at plugins/<plugin-name>/.codex-plugin/plugin.json. This file contains required fields such as the plugin name, version, description, and interface specifications that the Codex runtime uses to load and execute the plugin.

How does the repository handle plugin discovery and categorization?

The repository maintains two marketplace definition files at /.agents/plugins/marketplace.json and /.agents/plugins/api_marketplace.json. These JSON files enumerate all available plugins, including their filesystem paths, installation policies, and category assignments. The files regenerate automatically when new plugins are added to the plugins/ directory.

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

Beyond the required plugin.json manifest, a plugin directory may contain .app.json for native app connectors, .mcp.json for Multi-Channel-Protocol configurations, an assets/ folder for UI resources, a skills/ directory for reusable functions, an agents/ folder for YAML-defined agents, and a tests/ directory for validation suites.

How can developers scaffold a new plugin that conforms to the repository structure?

Developers can use the Python helper script located at /.agents/skills/plugin-creator/scripts/create_basic_plugin.py. This utility generates the standard directory layout and manifest template, ensuring the new plugin integrates correctly with the marketplace metadata system and follows the established naming conventions.

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