How to Configure Brand Colors and Logos in a Plugin's Interface Section

Configure brand colors and logos in the interface object of your plugin's plugin.json file using the brandColor, composerIcon, logo, and optional logoDark fields with relative paths to image assets.

Every plugin in the openai/plugins repository defines its visual identity within the interface section of the plugin.json file located under the plugin's .codex-plugin directory. This configuration controls how your plugin appears in the Codex UI, from accent colors used in buttons to the icons displayed in the marketplace. Understanding how to configure brand colors and logos in a plugin's interface section ensures your integration maintains consistent branding across the platform.

Understanding the Interface Configuration

The interface object resides in plugin.json within each plugin's .codex-plugin directory. This object contains metadata that dictates the visual presentation of your plugin within the Codex environment.

The Codex UI reads this configuration at load time and applies the values automatically. The brandColor injects into CSS variables controlling UI accents, while the composerIcon loads as an image element in the plugin selector.

Available Branding Fields

The interface object supports several fields for customizing your plugin's appearance:

• brandColor: A hex color string (e.g., "#0B5CFF") that sets the primary accent color for buttons, headers, and interactive elements throughout the plugin UI.

• composerIcon: A relative path to a small icon (typically ≤32px) displayed in the plugin composer or toolbar, helping users quickly identify your plugin among others.

• logo: A relative path to the main logo image shown on the plugin's detail page and marketplace listings.

• logoDark (optional): A relative path to a dark-mode variant of your logo, displayed when users prefer dark UI themes.

• screenshots (optional): An array of relative paths to PNG or JPEG files that illustrate the plugin's functionality in the marketplace.

All paths must be relative to the plugin's root directory, typically formatted as ./assets/filename.ext.

Configuration Examples

Minimal Configuration

For a basic setup requiring only a brand color:

{
  "interface": {
    "displayName": "MyPlugin",
    "shortDescription": "Do something useful",
    "brandColor": "#123456"
  }
}

Complete Configuration with Dark Mode Support

The following example from the Zoom plugin demonstrates all branding fields:

{
  "interface": {
    "displayName": "Zoom",
    "shortDescription": "Use Zoom meeting context and build Zoom integrations.",
    "longDescription": "Zoom connects Codex with your meeting data...",
    "brandColor": "#0B5CFF",
    "composerIcon": "./assets/zoom-small.svg",
    "logo": "./assets/app-icon.svg",
    "logoDark": "./assets/app-icon-dark.svg",
    "screenshots": [
      "./assets/screenshot-1.png",
      "./assets/screenshot-2.png"
    ]
  }
}

Updating an Existing Plugin

To customize branding for an existing plugin like Slack:

1. Place your custom icon in plugins/slack/.codex-plugin/assets/custom-icon.png.

2. Update the interface section in plugins/slack/.codex-plugin/plugin.json:

{
  "interface": {
    "brandColor": "#611F69",
    "composerIcon": "./assets/custom-icon.png",
    "logo": "./assets/custom-icon.png"
  }
}

3. Commit the changes. The UI automatically picks up the new branding on the next load.

Reference Implementations in openai/plugins

The repository provides concrete examples of interface configuration:

• Zoom: plugins/zoom/.codex-plugin/plugin.json contains a complete implementation with brandColor, composerIcon, logo, and logoDark fields.

• Slack: plugins/slack/.codex-plugin/plugin.json demonstrates a simpler configuration using brandColor, composerIcon, and logo without dark mode variants.

These files serve as templates when creating or customizing branding for any plugin in the repository.

Summary

• Configure branding in the interface object of .codex-plugin/plugin.json.
• Use brandColor for hex color values and composerIcon for toolbar icons.
• Provide logo for marketplace listings and optional logoDark for dark mode support.
• Store all image assets in the plugin's assets folder and reference them with relative paths starting with ./assets/.
• Changes take effect automatically when the UI reloads the plugin configuration.

Frequently Asked Questions

Where is the interface configuration defined in the openai/plugins repository?

The interface configuration is defined in the plugin.json file located within each plugin's .codex-plugin directory. For example, the Slack plugin configuration resides at plugins/slack/.codex-plugin/plugin.json, while the Zoom plugin uses plugins/zoom/.codex-plugin/plugin.json.

What image formats are supported for logos and icons?

The repository accepts standard web image formats including PNG, SVG, and JPEG. The composerIcon should be optimized for small display (≤32px), while the logo can be larger for marketplace display. Ensure all files exist in the plugin's assets folder before referencing them.

Is the logoDark field required for all plugins?

No, logoDark is optional. If omitted, the UI will use the standard logo image in both light and dark modes. However, providing a dark variant ensures optimal visibility and professional appearance when users enable dark themes in the Codex interface.

How do I verify my branding changes are working correctly?

After committing changes to your plugin's plugin.json and asset files, reload the Codex UI. The system reads the configuration at load time and automatically applies the new brandColor to CSS variables and renders the specified icons in the composer and marketplace views. Verify that the composerIcon appears in the plugin toolbar and the logo displays correctly on the detail page.

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