How to Find Available Codex Plugins in the OpenAI Plugins Repository

To find available Codex plugins in the openai/plugins repository, scan the plugins/ directory for subdirectories containing a .codex-plugin/plugin.json manifest file, or query the .agents/plugins/marketplace.json index for a programmatic list of all valid plugins.

The openai/plugins repository hosts a collection of ready-to-use Codex plugins, each organized as a standalone subdirectory under the top-level plugins/ folder. Every valid plugin must contain a mandatory manifest file at .codex-plugin/plugin.json that defines its metadata and capabilities. Understanding this repository structure allows you to quickly discover and enumerate all available Codex plugins using either manual browsing or automated scripts.

Repository Structure and Plugin Discovery

The plugins/ Directory Layout

According to the repository's top-level README.md, every Codex plugin resides in its own subdirectory under plugins/<name>/. The repository includes directories such as plugins/zoom/, plugins/box/, and plugins/zotero/, among others. This flat structure makes it straightforward to identify candidate plugins by listing the contents of the plugins/ folder.

The Manifest File Convention

A directory is only recognized as a valid Codex plugin if it contains a hidden .codex-plugin subdirectory with a plugin.json file. This manifest stores critical metadata including the plugin's name, version, description, homepage, repository URL, keywords, and asset references. The presence of this file is the definitive marker that distinguishes valid plugins from other directories in the repository.

Methods to List Available Codex Plugins

Method 1: Browse the plugins/ Directory

The simplest approach to find available Codex plugins is to enumerate the subdirectories of plugins/ and verify each contains the manifest file. Any folder lacking .codex-plugin/plugin.json is ignored by Codex tooling and should not be considered a valid plugin.

Method 2: Query the Marketplace Index

For programmatic discovery, the repository maintains an auto-generated marketplace index at .agents/plugins/marketplace.json. This JSON file aggregates all plugin names and their manifest locations, providing a machine-readable registry of every available plugin without requiring filesystem traversal.

import json
from pathlib import Path

repo_root = Path(__file__).parent  # adjust if run from elsewhere

marketplace_path = repo_root / ".agents/plugins/marketplace.json"

with marketplace_path.open() as f:
    marketplace = json.load(f)

for entry in marketplace["plugins"]:
    name = entry["name"]
    manifest_path = repo_root / entry["manifest"]
    with manifest_path.open() as mf:
        meta = json.load(mf)
    print(f"{name:20} {meta['version']} – {meta['description']}")

Method 3: Command-Line Discovery

You can locate all plugin manifests directly from the filesystem or using Git commands to parse the repository structure.

Using find to list plugin directories:

find plugins -type f -path "*/.codex-plugin/plugin.json" -printf '%h\n' | sed 's|plugins/||'

Using git ls-files to read manifests directly (works even without a working tree):

git ls-files "plugins/*/.codex-plugin/plugin.json" | while read -r file; do
    jq -r '"\(.name) \(.version) – \(.description)"' "$file"
done

Key Files for Plugin Discovery

Understanding these specific file paths helps you navigate the repository efficiently:

• README.md: Explains the repository layout and the requirement that each plugin must contain .codex-plugin/plugin.json.
• plugins/<plugin>/.codex-plugin/plugin.json: The canonical manifest defining the plugin's metadata (e.g., plugins/zoom/.codex-plugin/plugin.json).
• .agents/plugins/marketplace.json: The centralized index pointing to every plugin directory for programmatic lookup.
• plugins/<plugin>/SKILL.md (optional): Human-readable documentation detailing the plugin's capabilities and usage.
• plugins/<plugin>/assets/ (optional): Directory containing icons and screenshots referenced by the manifest.

Summary

• The openai/plugins repository organizes Codex plugins as subdirectories under plugins/, each requiring a .codex-plugin/plugin.json manifest to be recognized as valid.
• Manual discovery involves browsing the plugins/ directory and verifying the presence of the manifest file.
• Programmatic discovery uses the .agents/plugins/marketplace.json index to enumerate all available plugins and their metadata.
• Command-line tools like find and git ls-files can quickly list all valid plugin directories by searching for the manifest path pattern.

Frequently Asked Questions

What makes a directory a valid Codex plugin in the openai/plugins repository?

A directory is recognized as a valid Codex plugin only if it contains a .codex-plugin/plugin.json manifest file. This file contains mandatory metadata including the plugin name, version, and description. Directories without this file are ignored by Codex tooling even if they exist under the plugins/ folder.

Where is the complete list of available plugins stored?

The complete list is maintained in .agents/plugins/marketplace.json. This auto-generated JSON file serves as a marketplace index, referencing every plugin directory and its manifest location for programmatic discovery.

Can I discover plugins without cloning the repository?

Yes. You can use git ls-files to list manifest files directly from the remote repository without a full working tree, or browse the GitHub web interface to view the plugins/ directory structure and the marketplace JSON file.

What optional files might I find in a plugin directory?

Beyond the required manifest, plugin directories may contain a SKILL.md file documenting the plugin's capabilities and an assets/ directory containing icons and screenshots referenced by the manifest.

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