How Marketplace Plugins Reference External Plugin Sources in OpenAI Plugins

Marketplace plugins in the openai/plugins repository reference external sources by defining a repository or url field in their .codex-plugin/plugin.json manifest, enabling the marketplace to treat the local directory as a thin wrapper that pulls code from upstream Git repositories at runtime.

The openai/plugins repository powers the Codex plugin marketplace, where plugin metadata resides under the plugins/ directory. While many plugins bundle all assets locally, marketplace plugins can reference external plugin sources using specific JSON manifest fields that point to upstream repositories, creating a wrapper pattern that separates localized metadata from distributed source code.

Understanding the Plugin Manifest Structure

Every marketplace-ready plugin includes a .codex-plugin/plugin.json manifest that describes its identity, capabilities, and—crucially—its source location.

The .codex-plugin/plugin.json File

Located at plugins/<plugin-name>/.codex-plugin/plugin.json, this manifest contains the metadata required by the marketplace UI and installer. When referencing external sources, the manifest uses these specific fields:

• repository: The definitive Git URL where the upstream plugin source code lives (e.g., https://github.com/vercel/vercel-plugin). The marketplace installer clones this URL to fetch the latest code.
• url: A direct URL to the upstream source repository, typically used by the marketplace UI to display "View source" links.
• source: Often included within longDescription or as a standalone field, indicating the human-readable upstream repo name (e.g., vercel/vercel-plugin).

How External Source Detection Works

The marketplace distinguishes between fully local plugins and external-source wrappers through a specific detection process implemented in the source code.

The Wrapper Pattern

When a manifest contains a repository field pointing outside the current repository, the local plugins/<name>/ directory acts as a thin wrapper. This wrapper contains only metadata—such as icons, descriptions, and the manifest file—while the actual skill modules, agents, and commands reside in the external repository.

Detection Logic

As implemented in openai/plugins, the marketplace code reads each plugin's manifest and checks the repository field. If the value starts with https:// and does not resolve to a path inside the current repository, the system flags the plugin as having an external source.

import json
import pathlib

def load_plugin_manifest(name: str) -> dict:
    """Load manifest and detect external source references."""
    manifest_path = pathlib.Path("plugins") / name / ".codex-plugin" / "plugin.json"
    
    with manifest_path.open() as f:
        data = json.load(f)
    
    # Detect external source

    if data.get("repository", "").startswith("https://"):
        data["is_external"] = True
    else:
        data["is_external"] = False
    
    return data

Installation and Runtime Behavior

Referencing external sources changes how the marketplace handles plugin installation and updates.

Four-Stage External Source Workflow

1. Discovery: The marketplace enumerates all directories under plugins/ and reads each manifest at plugins/<name>/.codex-plugin/plugin.json.
2. External Source Detection: If the manifest includes a repository URL that does not resolve to the local repository, the marketplace records it as an external source.
3. Installation: When a user installs the plugin, the marketplace clones the external repository (using the repository URL) into a temporary sandbox, then loads assets from that location.
4. Updates: Because the source is external, updates pull automatically from the upstream repo on subsequent launches, ensuring the wrapper always reflects the latest upstream code.

This workflow enables a single source-of-truth model where developers maintain code in dedicated repositories while the openai/plugins repo hosts only the metadata wrapper.

Real-World Implementation Examples

Example 1: Vercel Plugin Wrapper

The Vercel plugin in plugins/vercel/.codex-plugin/plugin.json demonstrates a minimal wrapper pointing to an external repository:

{
  "name": "vercel",
  "displayName": "Vercel",
  "description": "Bring Vercel ecosystem guidance into Codex.",
  "url": "https://github.com/vercel",
  "repository": "https://github.com/vercel/vercel-plugin",
  "icon": "assets/icon.png",
  "longDescription": "Packages the upstream vercel/vercel-plugin skills, agents, and commands under the local `vercel` plugin identity for the Codex plugin marketplace."
}

Example 2: Shopify Plugin Wrapper

Similarly, the Shopify wrapper in plugins/shopify/.codex-plugin/plugin.json references a third-party repository:

{
  "name": "shopify",
  "displayName": "Shopify",
  "description": "Shopify AI Toolkit integration.",
  "url": "https://github.com/Shopify",
  "repository": "https://github.com/Shopify/Shopify-AI-Toolkit",
  "icon": "assets/logo.png",
  "longDescription": "Provides Shopify store management capabilities by delegating to the upstream Shopify-AI-Toolkit repository."
}

Key Files in the Repository

• plugins/vercel/.codex-plugin/plugin.json: Demonstrates a wrapper that points to https://github.com/vercel/vercel-plugin.
• plugins/shopify/.codex-plugin/plugin.json: Shows external source referencing for third-party integrations.
• .agents/plugins/marketplace.json: The registry listing all marketplace plugins, including those with external source entries.
• plugins/<plugin>/README.md: Per-plugin documentation that typically references the upstream repository for implementation details.

Summary

• Marketplace plugins reference external sources using the repository and url fields in .codex-plugin/plugin.json.
• The local directory acts as a thin wrapper containing only metadata, while actual code lives in the external repository.
• External plugins are detected when the repository field contains an https:// URL outside the current repo.
• During installation, the marketplace clones the external repository into a sandbox and loads assets from there.
• This pattern maintains a single source of truth for plugin code while allowing centralized marketplace discovery.

Frequently Asked Questions

How does the marketplace know if a plugin uses an external source?

The marketplace checks the repository field in plugins/<name>/.codex-plugin/plugin.json. If this field contains an HTTPS URL that does not resolve to a path inside the openai/plugins repository, the system flags it as an external source and sets is_external to true during manifest loading.

What is the difference between the url and repository fields in plugin.json?

The repository field provides the definitive Git URL used by the marketplace installer to clone the actual plugin code, while the url field typically points to the organization's homepage or repository root for UI display purposes. The installer relies on repository for code retrieval, whereas url drives "View source" links in the marketplace interface.

Can a marketplace plugin reference any public Git repository?

Yes, as long as the repository field contains a valid HTTPS Git URL and the repository structure matches the expected Codex plugin format. The marketplace clones this repository during installation, so the external source must be publicly accessible or use authentication methods supported by the marketplace installer.

Where does the marketplace store the external plugin code after installation?

The marketplace clones the external repository into a temporary sandbox environment during installation. The wrapper's local plugins/<name>/ directory only contains the manifest and metadata, while the actual skills, agents, and commands are loaded from the cloned external source at runtime.

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