How to Add Custom Branding Assets and App Icons to OpenAI Plugins

You add custom branding assets and app icons to an OpenAI plugin by creating an assets/ folder in the plugin root, placing your images there, and pointing to them via relative paths inside the interface object of the .codex-plugin/plugin.json manifest.

Every visual element an OpenAI Codex plugin displays in the marketplace or composer—from the marketplace logo to UI screenshots—is declared in a single JSON file. To add custom branding assets and app icons to plugins, you store image files in a dedicated assets/ directory and bind them through the manifest's interface field. The Codex platform reads these entries at bundle time and renders them across the plugin catalog and chat UI.

Locate the Plugin Manifest

The source of truth for all branding metadata is the .codex-plugin/plugin.json file located at the root of each plugin directory. Inside this manifest, the interface object contains the fields that the Codex runtime parses to display icons, screenshots, and accent colors according to the openai/plugins source code.

Step 1: Create the assets Directory

Create a folder named assets/ at the top level of your plugin folder, for example plugins/your-plugin/assets/. Keeping images under this directory keeps the repository organized and makes version control straightforward.

Step 2: Add Branding Image Files

Place your image files into the plugin's root assets/ directory. The following file types are commonly used to define a plugin's visual identity across the Codex platform:

• app-icon.svg or app-icon.png — the main icon shown in the plugin marketplace.
• A composer icon such as zoom-small.svg — the small icon rendered inside the prompt composer.
• One or more screenshot files in .png or .jpg format that illustrate the plugin's UI.
• An optional brandColor hex value for accent styling.

Step 3: Configure the Manifest interface

Open your .codex-plugin/plugin.json file and add or update the interface object with these branding fields:

• logo — Marketplace icon (e.g., "./assets/app-icon.svg")
• composerIcon — Icon in the prompt composer (e.g., "./assets/zoom-small.svg")
• screenshots — Gallery of UI screenshots (e.g., ["./assets/screen-1.png"])
• brandColor (optional) — Hex accent color (e.g., "#0B5CFF")

The following minimal manifest demonstrates the correct JSON structure:

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "A demo plugin with custom branding.",
  "interface": {
    "displayName": "My Plugin",
    "shortDescription": "Demo plugin",
    "brandColor": "#42A5F5",
    "logo": "./assets/app-icon.svg",
    "composerIcon": "./assets/composer-icon.svg",
    "screenshots": [
      "./assets/screen-1.png",
      "./assets/screen-2.png"
    ]
  },
  "apps": "./.app.json",
  "skills": "./skills/"
}

All paths are relative to the plugin root, so the assets must exist exactly where the manifest points.

Reference Implementation in the Zoom Plugin

The Zoom plugin in the openai/plugins repository demonstrates this pattern in production. Its manifest at plugins/zoom/.codex-plugin/plugin.json references ./assets/app-icon.svg for the marketplace logo and ./assets/zoom-small.svg for the composer icon. The plugin also bundles multiple screenshot images in the same assets/ folder, which the Codex runtime surfaces in the marketplace gallery.

If you are updating an existing plugin, you can swap assets without changing the manifest as long as the filenames and paths stay the same:

# Replace the Zoom plugin logo with your own branding

cp my-logo.svg plugins/zoom/assets/app-icon.svg

# Because plugin.json already points to ./assets/app-icon.svg, no JSON edit is required

Complete Folder Layout

A fully branded plugin follows this directory structure:

plugins/
└─ my-plugin/
   ├─ .codex-plugin/
   │   └─ plugin.json
   ├─ assets/
   │   ├─ app-icon.svg
   │   ├─ composer-icon.svg
   │   ├─ screen-1.png
   │   └─ screen-2.png
   └─ skills/
       └─ ...

Summary

• All branding metadata lives in the interface object of .codex-plugin/plugin.json.
• Place image files in a root-level assets/ folder and reference them with relative paths.
• Supported interface fields include logo, composerIcon, screenshots, and brandColor.
• The Zoom plugin in openai/plugins provides a concrete, production-ready example of this structure.

Frequently Asked Questions

What image formats are supported for plugin icons?

The reference implementation uses SVG for vector icons and PNG for screenshots. The Zoom plugin stores its marketplace logo as app-icon.svg, its composer icon as zoom-small.svg, and its gallery images as PNG files, so SVG and PNG are the expected formats.

Can I reference external URLs instead of local asset paths?

No. The manifest schema requires relative paths from the plugin root, such as ./assets/app-icon.svg. All branding files must reside inside the plugin repository so the Codex platform can bundle them correctly during deployment.

Which manifest field controls the composer icon?

The composerIcon field inside the interface object defines the small icon displayed when users interact with your plugin in the chat composer. For example, the Zoom plugin sets "composerIcon": "./assets/zoom-small.svg" to render its branded icon in the prompt UI.

How does the Codex platform know which assets to display?

The platform parses the interface object in .codex-plugin/plugin.json as the single source of truth. When the plugin is bundled, the runtime reads the logo, composerIcon, screenshots, and brandColor entries and injects them into the marketplace listing and composer interface automatically.

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