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

> Explore the openai/plugins repository structure. Discover its modular design, self-describing plugins, and marketplace definitions for seamless Codex integration and automatic plugin discovery. Understand the core architecture.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-09-13

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) – Default marketplace listing all locally-available plugins
- [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json)** – Links the plugin to a native app connector used by Codex runtimes
- **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.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:

```text
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main//.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`](https://github.com/openai/plugins/blob/main//.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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) generates the mandatory directory structure and manifest templates. It references [`plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugin-json-spec.md) for schema validation, ensuring that generated [`plugin.json`](https://github.com/openai/plugins/blob/main/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:

```python
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:

```python
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) describing its metadata and interface
- **Marketplace discovery** relies on auto-generated files at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/api_marketplace.json)
- **Optional configurations** include [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for native connectors and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) for protocol definitions
- **Developer tooling** at [`.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/marketplace.json) for the default experience and [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest and optional configuration files like [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) and advanced protocol handlers via [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) at the plugin root.