Codex plugins are installable bundles that encapsulate reusable Codex workflows, designed for sharing consistent setups across projects or teams. A plugin aggregates various components, including: Skills, which are prompts outlining workflows discoverable by the agent; Apps, representing optional application integrations or connector mappings; and MCP Servers, which are remote tools or shared contextual resources.

The core methodology for plugin management in Codex relies on a hierarchical, declarative configuration system centered around JSON-based manifest files and structured directories.

Plugin Structure:
Each plugin is a self-contained directory, typically named my-plugin/, with a specific internal organization:

• .codex-plugin/plugin.json: The mandatory plugin manifest, serving as the entry point and primary descriptor.
• skills/: An optional directory containing subdirectories for individual skills (e.g., skills/my-skill/SKILL.md). Skills are text files containing prompt instructions.
• .app.json: An optional file specifying app or connector mappings.
• .mcp.json: An optional file for MCP server configurations.
• assets/: An optional directory for visual assets like icons, logos, and screenshots.

Plugin Manifest (.codex-plugin/plugin.json):
This JSON file defines the plugin's metadata and points to its bundled components. Its primary roles are identification, component linking, and providing install-surface metadata. Key fields include:

• Identification: name (kebab-case identifier), version, description.
• Publisher Metadata: author, homepage, repository, license, keywords.
• Component Pointers: Paths to bundled components, relative to the plugin root:
  • "skills": "./skills/"
  • "mcpServers": "./.mcp.json"
  • "apps": "./.app.json"
• Interface Metadata (interface object): Controls how the plugin is presented in user interfaces.
  • displayName, shortDescription, longDescription: Titles and descriptive text.
  • developerName, category, capabilities: Publisher and functional attributes.
  • websiteURL, privacyPolicyURL, termsOfServiceURL: External links.
  • defaultPrompt: An array of suggested prompts for interaction.
  • brandColor, composerIcon, logo, screenshots: Visual presentation elements, with paths relative to the plugin root (e.g., "composerIcon": "./assets/icon.png").

Path Resolution: All paths within the plugin manifest (e.g., skills, mcpServers, apps, composerIcon) are defined as relative paths from the plugin's root directory, typically prefixed with ./.

Marketplace System:
Plugins are made available and discoverable through "marketplaces," which are JSON catalogs of plugins. Codex can consume marketplaces from three sources:

1. Curated Marketplace: The official Plugin Directory.
2. Repo Marketplace: Defined by a marketplace.json file located at $REPO_ROOT/.agents/plugins/marketplace.json.
3. Personal Marketplace: Defined by a marketplace.json file located at ~/.agents/plugins/marketplace.json.

Marketplace Metadata (marketplace.json):
This JSON file contains a list of plugin entries, each specifying details for a plugin's inclusion in the catalog:

• name: Identifier for the marketplace itself.
• interface.displayName: Display title for the marketplace in Codex.
• plugins: An array of plugin objects. Each plugin object within this array contains:
  • name: The plugin's identifier.
  • source: Defines how Codex locates the plugin files.
    • source: "local": Indicates a locally available plugin.
    • path: The path to the plugin's root directory. For repo installs, often ./plugins/my-plugin relative to the $REPO_ROOT/.agents/plugins/ directory. For personal installs, often ~/.codex/plugins/my-plugin. Critically, source.path is resolved relative to the marketplace file's location (the marketplace root).
  • policy: Dictates installation and authentication behavior.
    • installation: Values like AVAILABLE, INSTALLED_BY_DEFAULT, NOT_AVAILABLE.
    • authentication: Values like ON_INSTALL or ON_FIRST_USE.
  • category: A classification for the plugin (e.g., "Productivity").

Plugin Installation and Management:
When a plugin is "installed" from a marketplace, Codex copies its contents into a local cache directory: ~/.codex/plugins/cache/__INLINE_FORMULA_0__PLUGIN_NAME/__INLINE_FORMULA_1__VERSION component of the cache path is simply "local". This cached copy is what Codex loads and uses. Each plugin's enabled/disabled state is persisted in ~/.codex/config.toml. The source.path in the marketplace file merely points to the location for initial copying; subsequent operations use the cached version. Updating a local plugin requires updating its source directory and restarting Codex to trigger a refresh of the cached copy.