What Information Is Included in the Plugin Manifest's Interface Block?

The interface block in an OpenAI Codex plugin's plugin.json manifest defines the branding, capabilities, descriptive metadata, and UI assets required for platform integration.

The interface object inside a Codex plugin manifest serves as the declarative configuration that tells the OpenAI platform how to display, categorize, and interact with your plugin. Located in the .codex-plugin/plugin.json file (as seen in the openai/plugins repository), this block contains no executable logic but provides critical metadata for marketplace discovery and runtime behavior.

Core Fields in the Interface Block

According to the reference implementations in plugins/zoom/.codex-plugin/plugin.json and plugins/slack/.codex-plugin/plugin.json, the interface object requires specific fields that control how the plugin appears in the Codex UI and what functionality it exposes.

Branding and Visual Assets

The platform uses several fields to maintain consistent visual identity across light and dark modes:

• brandColor — The primary brand color for UI theming (e.g., #0B5CFF for Zoom).
• brandColorDark (optional) — The dark-mode variant of the brand color.
• logo — Path to the light-mode logo asset relative to the manifest (e.g., ./assets/logo.jpg).
• logoDark (optional) — Path to the dark-mode logo asset.
• composerIcon — Path to the icon displayed in the Codex composer UI (e.g., ./assets/composer-icon.svg).
• screenshots — Array of image paths for marketplace preview thumbnails.

Discovery and Descriptive Metadata

These fields control how users find and understand the plugin in the marketplace:

• displayName — The human-readable name shown in the plugin catalogue (e.g., Zoom or Slack).
• developerName — The name of the plugin's developer or organization.
• shortDescription — A concise tagline for list views (e.g., Smart meeting insights from Zoom).
• longDescription — A detailed paragraph explaining workflows and capabilities.
• category — High-level classification for discovery (e.g., Communication).

Interaction Capabilities

The capabilities array defines the permission scope for the plugin:

"capabilities": ["Interactive", "Read", "Write"]

• Interactive — Enables real-time user interactions.
• Read — Allows access to read data from the external service.
• Write — Permits write operations to the external service.

Legal and External Links

Every plugin must provide compliance and contact information:

• privacyPolicyURL — Link to the developer's privacy policy.
• termsOfServiceURL — Link to the terms of service agreement.
• websiteURL — Official website for the plugin provider.

Conversation Starters

The defaultPrompt array seeds the conversation with suggested starter prompts that help users begin interacting with the plugin immediately after installation.

Reading the Interface Block Programmatically

Since the manifest is strictly declarative JSON, you can safely parse the interface block without invoking any plugin logic. Below is a Node.js example for extracting metadata:

const fs = require('fs');
const path = require('path');

// Load a plugin manifest
const manifestPath = path.join(__dirname, 'plugins/zoom/.codex-plugin/plugin.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

// Access the interface section
const iface = manifest.interface;

console.log('Display name:', iface.displayName);
console.log('Capabilities:', iface.capabilities.join(', '));
console.log('Brand colour (light):', iface.brandColor);

When building a custom UI layer in React, you can import the manifest directly to apply dynamic theming:

import React from 'react';
import manifest from './plugins/slack/.codex-plugin/plugin.json';

const { brandColor, brandColorDark, logo, logoDark } = manifest.interface;

export const PluginHeader = () => (
  <header
    style={{
      background: `linear-gradient(${brandColor}, ${brandColorDark})`,
    }}
  >
    <img src={logo} alt="logo" className="light" />
    <img src={logoDark} alt="logo" className="dark" />
    <h1>{manifest.interface.displayName}</h1>
  </header>
);

Summary

• The interface block in .codex-plugin/plugin.json is a declarative configuration object with no executable code.
• Required fields include brandColor, capabilities, category, displayName, shortDescription, longDescription, and legal URLs.
• Optional fields such as brandColorDark, logoDark, and screenshots support adaptive UI themes.
• The capabilities array (Interactive, Read, Write) determines the plugin's permission scope.
• defaultPrompt provides starter prompts to guide user conversations.

Frequently Asked Questions

What file contains the interface block in an OpenAI plugin?

The interface block lives inside the plugin.json file located in the .codex-plugin directory at the root of your plugin folder. For example, Zoom's manifest is stored at plugins/zoom/.codex-plugin/plugin.json in the openai/plugins repository.

Are all fields in the interface block mandatory?

No. While fields like brandColor, capabilities, displayName, shortDescription, longDescription, privacyPolicyURL, and termsOfServiceURL are required for marketplace submission, assets such as brandColorDark, logoDark, and screenshots are optional but recommended for complete UI integration.

How does the capabilities field affect plugin behavior?

The capabilities array acts as a permission declaration that tells the Codex runtime what interactions the plugin supports. A plugin with only ["Read"] cannot execute write operations, while ["Interactive", "Read", "Write"] enables full bidirectional communication with the external service.

Can I update the interface block without changing plugin code?

Yes. Since the interface block is purely declarative metadata, you can modify branding, descriptions, or URLs in plugin.json without touching the implementation logic. However, changes to capabilities may require corresponding updates to the plugin's endpoint handlers to maintain consistency between declared and actual functionality.

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