Where Is the Plugins Directory Located in the OpenAI Codex Repository?

The plugins directory is located at the root level of the openai/plugins repository, directly under /plugins, and contains every Codex plugin implementation including manifests and skill definitions.

The openai/plugins repository serves as the central hub for OpenAI Codex integrations. Understanding the exact location and structure of the plugins directory is essential for developers looking to extend Codex functionality or contribute new integrations. The repository follows a flat, predictable layout that places all functional plugin code in a single top-level folder.

Exact Location of the Plugins Directory

The repository's top-level plugins folder contains every Codex plugin implementation. It lives directly under the root of the repository at:

/plugins

You can view this directory in the GitHub web interface at https://github.com/openai/plugins/tree/main/plugins.

Inside this folder, you will find subfolders for each supported service (e.g., zotero, figma, circleci). Each plugin package includes its own assets, a plugin.json manifest, and one or more SKILL markdown files that describe the plugin's capabilities.

Directory Structure and Organization

Root Level Layout

At the repository root, you will find only the README, git metadata, and a few helper directories (.agents, .gitignore). All functional code for Codex plugins lives under plugins/, making it the single source of truth for plugin implementations. By grouping every plugin under this top-level directory, the repository stays tidy and makes it easy for developers to discover, version, and extend the collection of Codex-compatible integrations.

Per-Plugin Subdirectories

Every subfolder within plugins/ follows a standard layout. For example, plugins/zotero/ contains:

• /.codex-plugin/plugin.json — The manifest that the Codex runtime loads. Example: plugins/zotero/.codex-plugin/plugin.json
• SKILL.md — Human-readable documentation of the skill. Example: plugins/zotero/SKILL.md
• Optional assets/, scripts/, and agents/ directories holding icons, helper scripts, and OpenAI-compatible agent definitions.

The same structure applies to other integrations like plugins/figma/ and plugins/circleci/, each containing their own .codex-plugin/plugin.json and SKILL.md files.

Navigating the Repository Programmatically

When working with a local clone of the openai/plugins repository, you can locate the plugins directory using Python's pathlib module:

import pathlib

# Path to the repository root (adjust as needed)

repo_root = pathlib.Path(__file__).resolve().parents[1]

# Absolute path to the plugins directory

plugins_dir = repo_root / "plugins"

print(f"The plugins directory is at: {plugins_dir}")

To enumerate all available plugins and verify their manifests programmatically:

import pathlib

repo_root = pathlib.Path(__file__).resolve().parents[1]
plugins_dir = repo_root / "plugins"

for plugin_path in plugins_dir.iterdir():
    if plugin_path.is_dir():
        manifest = plugin_path / ".codex-plugin" / "plugin.json"
        if manifest.exists():
            print(f"Found plugin: {plugin_path.name}")

This demonstrates that each plugin lives in its own subdirectory under the shared plugins folder, with the runtime loading configuration from .codex-plugin/plugin.json.

Summary

• The plugins directory is located at the root level (/plugins) of the openai/plugins repository.
• It contains all functional Codex plugin code, with the repository root reserved for documentation and configuration files like .agents and .gitignore.
• Each plugin subdirectory includes a .codex-plugin/plugin.json manifest and a SKILL.md documentation file.
• The flat structure enables easy discovery and versioning of integrations like Zotero, Figma, and CircleCI.

Frequently Asked Questions

What files are required inside each plugin subdirectory?

Each plugin must contain a .codex-plugin/plugin.json manifest file that defines the plugin's name, description, and authentication requirements. It should also include a SKILL.md file documenting the plugin's capabilities. Optional directories like assets/, scripts/, and agents/ may contain supporting resources.

Is the plugins directory the only location containing functional code?

Yes. According to the openai/plugins source code, the repository root contains only the README, git metadata, and helper directories like .agents. All functional code for Codex plugins resides exclusively under the plugins/ directory.

How does the Codex runtime locate plugin manifests?

The runtime scans the plugins/ directory and loads the plugin.json file found within each subdirectory's .codex-plugin/ folder. For example, the Zotero integration is loaded from plugins/zotero/.codex-plugin/plugin.json.

Can I add new plugins by creating subdirectories in the plugins folder?

Yes. Developers can create new plugin implementations by adding a subdirectory under plugins/ following the standard structure: create a .codex-plugin/plugin.json manifest and a SKILL.md documentation file, along with any necessary asset or script directories.

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