Codex plugin icons and metadata in Reliquary

Date: 2026-10-02

Answer for this repository

Reliquary is a Git repository at git.g4b.org:dirigence/reliquary. Codex can register that Git repository as the marketplace source. Inside its .agents/plugins/marketplace.json, each plugin has "source": "local" and a path such as ./plugins/spire. Here, local means relative to the fetched marketplace repository, not that users must install the marketplace from a local disk checkout. These are two different source levels. The marketplace file makes Spire and Tome discoverable, but does not define their icons. OpenAI Docs: marketplace sources and metadata

At the initial investigation, neither Spire nor Tome had an interface object or image assets, so the images in the screenshot were application fallbacks. Spire now has bundled artwork and explicit image paths; Tome still has no image assets or interface object. OpenAI's public documentation specifies how to supply an icon, but does not document the fallback-selection rule that produced the star for Spire and the document for Tome. Do not depend on those particular fallback images.

Set a deliberate icon

For Reliquary's current Codex compatibility manifests, put image paths in the plugin's .codex-plugin/plugin.json, under interface:

{
  "name": "spire",
  "version": "0.1.1",
  "description": "Spire — an agent orchestration system for structured development.",
  "author": { "name": "Gabor Körber", "email": "gab@g4b.org" },
  "skills": "./skills/",
  "interface": {
    "displayName": "Spire",
    "shortDescription": "Structured agent workflows",
    "longDescription": "Skills for session coordination, research, workpad use, and implementation.",
    "developerName": "Gabor Körber",
    "category": "Productivity",
    "capabilities": ["Skills", "Agents"],
    "logo": "./assets/spire_logo512.png",
    "composerIcon": "./assets/spire_icon512.png"
  }
}

Spire now stores the detailed logo at plugins/spire/assets/spire_logo512.png, the simpler composer icon at plugins/spire/assets/spire_icon512.png, and a 128 px emoji image for the READMEs at plugins/spire/assets/spire_logo128_emoji.png. Apply the same pattern under plugins/tome/ when Tome artwork is available. Paths begin with ./ and resolve from the plugin root (plugins/spire/), even though the manifest is in .codex-plugin/. The images must be included in the Git repository. logo is the primary listing image; composerIcon is the icon used in the composer. The same image can serve both fields if suitable. Optional logoDark and composerIconDark point to dark-theme variants. OpenAI Docs: manifest path rules, OpenAI Docs: listing metadata

This is the source-independent part of the solution: the manifest and image files travel together inside the plugin package. The same ./assets/spire_logo512.png reference resolves when Codex obtains the marketplace from git.g4b.org, another Git remote, a local checkout, or a copied package. No icon path should refer to G:\dev\..., a Git web URL, a user's home directory, or a folder outside the plugin root. Each consuming client must still refresh or reinstall its cached package after an update; source-independent paths do not imply instant updates.

Supported formats are PNG, JPEG, WebP, and SVG. Images must be square and at least 48 × 48 pixels, with a maximum file size of 5 MiB. Raster images cannot exceed 4096 pixels on either side. SVGs need a square numeric viewBox or square numeric dimensions of at least 48 × 48; dimensions cannot use units or percentages. screenshots is an optional array of paths to additional images. These are package-validation rules for distribution; for consistent behavior, follow them for this marketplace too. OpenAI Docs: image requirements, OpenAI Docs: image validation errors

Tome's minimal manifest still lacks several fields required by Codex package validation for distribution, including interface, logo, and composerIcon. Its appearance in this personal marketplace does not prove it would pass public submission validation. Spire has these fields now, although no public submission validation was run. OpenAI Docs: package and listing requirements

Other settings you can set

Plugin manifest: identity and components

Field	Purpose
`name`	Stable plugin identifier; keep it distinct from the display name.
`version`	Package version. Use an explicit semantic version for distribution and updates.
`description`	Package summary.
`author`	Publisher name, optionally email and HTTPS URL.
`homepage`, `repository`, `license`, `keywords`	Optional project and discovery metadata. `homepage` does not automatically populate the listing website link.
`skills`	In the Codex compatibility format, a relative skills directory such as `./skills/`. Spire and Tome should declare this if they intend their bundled skills to be loaded in that format.
`mcpServers`	In the Codex compatibility format, a path to bundled MCP server configuration if the plugin includes an MCP server.
`apps`	Mapping to registered MCP apps via `.app.json`, when relevant.
`hooks`	Optional lifecycle hook configuration; hook scripts need user trust and must exist in the execution environment.

Tome's manifest omits skills; Spire and several other Reliquary plugins now explicitly include "skills": "./skills/". The official compatibility-format field reference says to use skills for Codex packages with skills. This report does not test whether a particular installed copy auto-discovers Tome's skills without that declaration. OpenAI Docs: package components, OpenAI Docs: hooks and MCP servers

`interface`: what people see

Field	Purpose
`displayName`	Name shown to users.
`shortDescription`	Short subtitle beside or below the name.
`longDescription`	Fuller explanation of tasks, audience, and limitations.
`developerName`	Publisher label.
`category`	Directory category.
`capabilities`	Labels describing what the plugin provides, such as `Skills`.
`websiteURL`, `supportURL`, `privacyPolicyURL`, `termsOfServiceURL`	Listing and support links; the four URLs are required for public review of an attached MCP app.
`defaultPrompt`	One starter prompt or an array of up to three.
`brandColor`, `brandColorDark`	Light and dark theme accent colors.
`logo`, `logoDark`	Primary listing image and optional dark variant.
`composerIcon`, `composerIconDark`	Composer icon and optional dark variant.
`screenshots`	Optional image paths for the listing.

For public submission, the documented text limits include 30 characters each for displayName and shortDescription, 4000 for longDescription, and 80 for developerName; defaultPrompt allows up to three prompts of 128 characters each. The public format requires displayName, both descriptions, developerName, category, capabilities, logo, and composerIcon for Codex packages. Local or private marketplace display may tolerate incomplete metadata, as the current screenshot demonstrates. OpenAI Docs: listing fields and limits

Marketplace catalog: availability, not artwork

Reliquary's .agents/plugins/marketplace.json controls the marketplace title (interface.displayName), plugin ordering, plugin folder paths, category, and install policy. Each entry can set policy.installation (for example AVAILABLE, INSTALLED_BY_DEFAULT, or NOT_AVAILABLE) and policy.authentication (authentication on install or first use). The catalog can point to plugin folders within the Git marketplace checkout via source: "local"; it can also point to separate Git-backed plugin sources using source: "url" or source: "git-subdir". It does not carry logo or composerIcon for each plugin. OpenAI Docs: marketplace metadata

Portable format and public publication

OpenAI now recommends a root plugin.json for portable Agent Plugins packages. In that format, package identity stays at the root, components use skills/ and mcp.json, and OpenAI presentation fields go under extensions.com.openai.interface. The existing .codex-plugin/plugin.json remains a supported compatibility fallback. If a root plugin.json has an extensions.com.openai object, OpenAI uses that object for OpenAI-specific settings instead of the compatibility manifest; the two are not merged. If Reliquary adopts the portable format later, move icon and interface metadata together so a stale compatibility manifest does not mislead maintainers. OpenAI Docs: portable and compatibility manifests

For public submissions, additional extensions.com.openai settings include onboardingSkill, review test cases and demo recording for MCP apps, and publication countries, release notes, and translations. These belong to submission and publication workflows and are not needed just to display a custom icon in Reliquary's marketplace. OpenAI Docs: review and publication fields

Do other harnesses read these icon fields?

The asset file is reusable, but icon metadata is currently client-specific:

Consumer	Field to use	What is documented
Codex / OpenAI plugin listing	`.codex-plugin/plugin.json` → `interface.logo`; `interface.composerIcon` for the composer	OpenAI reads these presentation fields. In a future portable root `plugin.json`, put them under `extensions.com.openai.interface` instead.
Anthropic plugin directory	`.claude-plugin/plugin.json` → top-level `icon`, pointing to an image inside the plugin such as `./assets/logo.png`	Anthropic says its directory reads the field when a plugin is submitted. Claude Code ignores the field at plugin load time.
Portable Agent Plugins 1.0 specification	No standard icon or logo field	Its root `plugin.json` schema is closed. Client-specific presentation belongs under `extensions`; other clients ignore extensions they do not implement.

Thus adding OpenAI's interface.logo alone does not make every harness show that logo. Spire now references one image file at plugins/spire/assets/spire_logo512.png from Codex's interface.logo and Claude's top-level icon in its separate manifest. Even then, there is no documented guarantee that Claude Code's own marketplace UI will render that icon field: its docs explicitly say Claude Code ignores it at load time. The repo and plugin READMEs also reference the emoji image so the branding appears in ordinary Markdown views. Claude Code plugin manifest reference, Agent Plugins manifest, Agent Plugins client extensions

Suggested workflow for Reliquary

Put the existing Spire and Tome artwork in each plugin's own assets/ directory, using a supported square image format.
Add interface.logo and interface.composerIcon to each .codex-plugin/plugin.json; add the other interface fields needed for readable listing copy. Add skills: "./skills/" where appropriate.
If Anthropic directory listing is a target, reference each same image from the corresponding .claude-plugin/plugin.json via its separate top-level icon field. If the repository README should show the logo in every harness, add a normal relative Markdown image there as well.
Validate the JSON and asset paths locally, then commit and push the repository changes to git.g4b.org.
Refresh the registered Git marketplace (codex plugin marketplace upgrade reliquary is the documented CLI form), then refresh or reinstall the plugin in the desktop Plugins view and inspect the icon. Installed plugins are copied into a cache; changing the source repository alone need not update an already installed copy immediately. Use codex plugin marketplace list to confirm which marketplace source Codex is tracking. OpenAI Docs: marketplace CLI and installed copies

Spire's manifest and README changes were implemented after the initial report; Tome remains pending artwork.

13 KiB Raw Permalink Blame History Unescape Escape