Managing Plugin Assets and Referencing Icons in OpenAI Plugins: A Complete Guide

OpenAI plugins store visual assets in a dedicated assets/ directory and reference them via relative paths in the .codex-plugin/plugin.json manifest using the icon, appIcon, and logo fields.

The openai/plugins repository standardizes how static resources are bundled and served across all plugin implementations. Understanding the relationship between the manifest configuration and the filesystem structure ensures your plugin renders correctly in the OpenAI marketplace and internal UI components.

How Assets Are Organized in OpenAI Plugins

Each plugin in the repository follows a consistent directory structure where visual assets live in a top-level assets/ folder. The manifest file located at .codex-plugin/plugin.json uses relative paths to map these files to specific UI elements.

Directory Structure Convention

All paths in the manifest resolve relative to the plugin root directory. For example, in the mem plugin, the structure appears as:

plugins/mem/
├── .codex-plugin/
│   └── plugin.json
└── assets/
    ├── icon.png
    ├── app-icon.png
    └── logo.png

Manifest Asset Fields

The plugin manifest supports three primary asset keys:

• icon: The square marketplace icon displayed next to the plugin name (typically 32×32 or 64×64 pixels)
• appIcon: The favicon-style badge used inside the plugin's UI interface
• logo: The full-size branding image shown on detail pages

Configuring the Plugin Manifest

The .codex-plugin/plugin.json file must explicitly declare asset locations. In plugins/mem/.codex-plugin/plugin.json, the configuration specifies:

{
  "name": "mem",
  "title": "Mem",
  "description": "AI-powered memory for agents.",
  "icon": "assets/icon.png",
  "appIcon": "assets/app-icon.png",
  "logo": "assets/logo.png"
}

The runtime resolves these relative paths automatically and serves files through the plugin's static assets endpoint. This allows UI components to reference the same images without host-side path manipulation.

Supported Asset Formats and Optimization

OpenAI plugins support raster and vector formats, each suited for different use cases:

• PNG: Use for general raster icons requiring transparency. Keep files under 50KB to prevent marketplace loading delays.
• SVG: Preferred for appIcon and logo fields. Vector graphics scale cleanly on high-DPI displays and maintain small file sizes.
• ICO: Rarely needed; only include if targeting legacy browser compatibility requirements.

When updating visual assets, always increment the manifest version field to invalidate cached images across the platform.

Accessing Assets in Plugin Code

When building UI components, import assets directly to ensure path consistency with the manifest:

import IconUrl from "./assets/icon.png";

function PluginHeader() {
  return (
    <header>
      <img src={IconUrl} alt="Plugin icon" width={32} height={32} />
      <h1>My Plugin</h1>
    </header>
  );
}

The build pipeline copies the entire assets/ directory into the final artifact, preserving the relative structure defined in the manifest.

Real-World Examples from the Repository

Mem Plugin (PNG Implementation)

The mem plugin uses PNG assets for all visual elements:

• Manifest: plugins/mem/.codex-plugin/plugin.json
• Icon: plugins/mem/assets/icon.png
• App Icon: plugins/mem/assets/app-icon.png

Figma Plugin (SVG Implementation)

The figma plugin demonstrates vector-based asset management:

• Manifest: plugins/figma/.codex-plugin/plugin.json
• Icon: plugins/figma/assets/icon.svg
• Logo: plugins/figma/assets/figma.svg

ZoomInfo Plugin (Mixed Formats)

The zoominfo plugin combines SVG and PNG assets:

• Manifest: plugins/zoominfo/.codex-plugin/plugin.json
• App Icon: plugins/zoominfo/assets/app-icon.svg

These implementations confirm that the manifest loader accepts both formats interchangeably when referenced correctly.

Summary

• Store all visual assets in the assets/ directory at the plugin root level
• Reference files using relative paths in .codex-plugin/plugin.json via icon, appIcon, and logo fields
• Use SVG for scalable icons and PNG for raster graphics requiring complex transparency
• Update the manifest version field when changing assets to clear platform caches
• Import assets directly in code to maintain path synchronization with the manifest configuration

Frequently Asked Questions

What directory should I use for plugin assets in OpenAI plugins?

Place all static assets in a top-level assets/ directory within your plugin folder. The manifest at .codex-plugin/plugin.json references these files using relative paths like assets/icon.png. The build system automatically bundles this directory into the final plugin artifact.

Can I use SVG files for OpenAI plugin icons?

Yes. The manifest supports SVG files for the icon, appIcon, and logo fields. The figma plugin demonstrates this in plugins/figma/assets/icon.svg. Vector graphics provide better scaling on high-resolution displays and typically produce smaller file sizes than PNG equivalents.

How do I update an existing plugin icon in the OpenAI plugins repository?

Replace the file in plugins/<name>/assets/ and increment the version field in .codex-plugin/plugin.json. Commit both changes simultaneously to ensure the platform recognizes the new asset. The version bump invalidates cached images across the marketplace and plugin UI.

What is the difference between icon and appIcon in the plugin manifest?

The icon field specifies the marketplace listing image displayed alongside the plugin name in search results. The appIcon field defines the smaller badge used inside the plugin's own interface, such as navigation bars or headers. The mem plugin uses both fields in plugins/mem/.codex-plugin/plugin.json to distinguish between marketplace presentation and in-app branding.

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