How to Add Apps to a Plugin in the OpenAI Plugins Repository

To add an app to a plugin in the OpenAI Plugins repository, edit the .app.json file in the plugin directory to register the new app ID, then optionally bump the version in plugin.json.

Adding apps to a plugin requires no code changes in the OpenAI Plugins monorepo. Each plugin stores its app registry in a JSON configuration file that the runtime loads at startup, making app registration a pure data-entry task. This guide explains the exact file paths and JSON structures required to extend any plugin with new apps.

Understanding the Plugin App Registry

In the openai/plugins repository, every plugin is a self-contained directory under plugins/. The app registry lives in a file named .app.json at the root of the plugin folder. The plugin metadata file located at plugins/<plugin>/.codex-plugin/plugin.json points to this registry via the field:

"apps": "./.app.json"

At runtime, the generic loader reads .app.json and exposes the app IDs to the OpenAI Connector service. Because the system reads these IDs dynamically, you only need to update the JSON file to add functionality.

Step-by-Step Guide: How to Add Apps to a Plugin

Follow these four steps to register a new app in any plugin.

1. Obtain a New App ID

App IDs are generated by the OpenAI Connector service when you register a new app in the Marketplace. For internal development, you may use a placeholder following the format connector_<random-hex> or asdk_app_<hash>.

2. Edit the Plugin's .app.json

Navigate to plugins/<plugin>/.app.json and insert a new entry under the top-level "apps" object. Use snake-case naming that matches the plugin's internal naming convention.

3. Update the Plugin's plugin.json (Optional)

If the new app changes the plugin's public API or you intend to publish a new version, increment the "version" field in plugins/<plugin>/.codex-plugin/plugin.json.

4. Commit the Changes

Submit your changes to the repository. The CI pipeline runs validation checks to ensure the JSON is well-formed and that all referenced app IDs are unique across the registry.

Code Examples: Adding Apps to Existing Plugins

Adding an App to the Google Calendar Plugin

To add a new app named google-calendar-export to the Google Calendar plugin, edit plugins/google-calendar/.app.json:

{
  "apps": {
    "google-calendar": {
      "id": "connector_947e0d954944416db111db556030eea6"
    },
    "google-calendar-export": {
      "id": "connector_5f3a1b2c9d7e4a8b9c0d1e2f3a4b5c6d"
    }
  }
}

Optionally bump the version in plugins/google-calendar/.codex-plugin/plugin.json:

{
  "name": "google-calendar",
  "version": "1.0.3",
  "description": "Google Calendar connector",
  "apps": "./.app.json"
}

Adding an App to the ZoomInfo Plugin

For the ZoomInfo plugin located at plugins/zoominfo/, add entries to .app.json following the same structure:

{
  "apps": {
    "zoominfo": {
      "id": "asdk_app_698a340b9230819188ba5a5eea79022d"
    },
    "zoominfo-company-search": {
      "id": "asdk_app_9f1c2d3e4b5a6c7d8e9f0a1b2c3d4e5f"
    }
  }
}

Summary

• App registry location: Each plugin stores its apps in plugins/<plugin>/.app.json.
• Metadata reference: The file plugins/<plugin>/.codex-plugin/plugin.json links to the registry via "apps": "./.app.json".
• No code required: Adding an app is a data-entry task; the runtime loads IDs from JSON at startup.
• Validation: The repository CI ensures JSON validity and ID uniqueness automatically.
• Versioning: Update the version field in plugin.json only when publishing API changes.

Frequently Asked Questions

What is the .app.json file?

The .app.json file is the app registry for a specific plugin. It contains a top-level "apps" object that maps snake-case app names to their connector IDs, which the OpenAI Connector service uses to route requests at runtime.

Do I need to write code to add a new app to a plugin?

No. According to the openai/plugins source code, the repository contains no custom code for handling individual apps. The generic loader reads the .app.json file at runtime, so adding an app requires only editing that JSON file.

Where do app IDs come from?

Production app IDs are generated by the OpenAI Connector service when you register the app in the Marketplace. For local development or testing, you can use placeholder IDs following the patterns connector_<random-hex> or asdk_app_<hash>.

When should I update the plugin version?

Increment the "version" field in plugins/<plugin>/.codex-plugin/plugin.json only when the new app changes the plugin's public API or when you are ready to publish a new release. Pure app additions that do not affect the API surface do not require version bumps.

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