# Codex Plugin Marketplace Support for Reliquary

Date: 2026-05-30

## Summary

Reliquary is already a Claude plugin marketplace, and the current Codex installation can consume it today through the existing `.claude-plugin/marketplace.json` layout. In the local Codex CLI 0.135.0-alpha.1 environment, the `reliquary` marketplace is configured from `git@git.g4b.org:dirigence/reliquary.git`, and `g4b_ai`, `gitea`, and `project-uv` are installed and enabled.

For long-term portability, Reliquary should publish a parallel Codex-native marketplace layout instead of relying on Codex's compatibility with Claude marketplace metadata. The practical target is:

- keep `.claude-plugin/marketplace.json` for Claude Code
- add `.agents/plugins/marketplace.json` for Codex
- keep each plugin's existing `.claude-plugin/plugin.json`
- add each plugin's `.codex-plugin/plugin.json`
- keep shared skill content under `plugins/<plugin>/skills/<skill>/SKILL.md`

The skill directories can remain shared between Claude and Codex. The main work is metadata and install documentation.

## Current Repository State

The repo root currently has:

- `.claude/settings.json`, which configures Claude to know the `reliquary` marketplace and enable selected plugins.
- `.claude-plugin/marketplace.json`, which declares the marketplace and four plugins: `g4b_ai`, `dioxus`, `project-uv`, and `gitea`.
- `plugins/<plugin>/.claude-plugin/plugin.json` for `g4b_ai`, `gitea`, and `project-uv`.
- shared skills under `plugins/<plugin>/skills/.../SKILL.md`.

The repo-level `CLAUDE.md` already tells Claude users that this repo is a marketplace and that workpad material lives under `docs/workpad/`.

## Observed Codex Behavior

Codex is already configured locally with:

```toml
[marketplaces.reliquary]
source_type = "git"
source = "git@git.g4b.org:dirigence/reliquary.git"

[plugins."g4b_ai@reliquary"]
enabled = true

[plugins."gitea@reliquary"]
enabled = true

[plugins."project-uv@reliquary"]
enabled = true
```

Running the local Codex binary's plugin listing showed:

```text
Marketplace `reliquary`
g4b_ai@reliquary      installed, enabled  0.1.0
dioxus@reliquary      not installed
project-uv@reliquary  installed, enabled  0.1.0
gitea@reliquary       installed, enabled  0.1.0
```

That proves Codex can currently discover this repo's Claude marketplace file. However, Codex's own plugin creation guidance uses `.codex-plugin/plugin.json` for plugin manifests and `.agents/plugins/marketplace.json` for marketplace files, so Reliquary should add those files explicitly rather than treating Claude metadata as the only source of truth.

## Codex-Native Marketplace Shape

OpenAI's Codex plugin creator skill describes Codex plugin scaffolds as containing a required `.codex-plugin/plugin.json`, optional `skills/`, and marketplace entries in `.agents/plugins/marketplace.json`. Its reference schema shows `skills: "./skills/"` in the plugin manifest and Codex marketplace entries with `source`, `policy`, and `category` fields.

Recommended repo-level Codex marketplace file:

```text
.agents/plugins/marketplace.json
```

Recommended shape:

```json
{
  "name": "reliquary",
  "interface": {
    "displayName": "Reliquary"
  },
  "plugins": [
    {
      "name": "g4b_ai",
      "source": {
        "source": "local",
        "path": "./plugins/g4b_ai"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}
```

Each current plugin should get a Codex manifest:

```text
plugins/g4b_ai/.codex-plugin/plugin.json
plugins/gitea/.codex-plugin/plugin.json
plugins/project-uv/.codex-plugin/plugin.json
plugins/dioxus/.codex-plugin/plugin.json
```

Recommended minimal manifest shape:

```json
{
  "name": "g4b_ai",
  "version": "0.1.0",
  "description": "Gabor's personal Codex skills: workpad, research-tree, implementation-orchestration, markdown-embedded-svg.",
  "author": {
    "name": "Gabor Körber",
    "email": "gab@g4b.org"
  },
  "skills": "./skills/",
  "interface": {
    "displayName": "g4b_ai",
    "shortDescription": "Personal project workflow skills for Codex.",
    "longDescription": "Workpad placement, research orchestration, implementation orchestration, and Markdown SVG guidance.",
    "developerName": "Gabor Körber",
    "category": "Productivity",
    "capabilities": ["Skills"]
  }
}
```

The existing `.claude-plugin/plugin.json` files can stay as-is. The `.codex-plugin` files can point at the same `skills/` folders.

## How Users Would Install from Codex

Once the Codex marketplace file exists, a Codex user can add this marketplace from the repo:

```powershell
codex plugin marketplace add git@git.g4b.org:dirigence/reliquary.git
```

Then install the desired plugin:

```powershell
codex plugin add g4b_ai@reliquary
```

For local development from a checked-out repo, Codex also supports local marketplace sources:

```powershell
codex plugin marketplace add G:\dev\projects\reliquary
codex plugin add g4b_ai@reliquary
```

The local Codex help confirms the relevant command forms:

- `codex plugin marketplace add <SOURCE>`
- `codex plugin marketplace list`
- `codex plugin marketplace upgrade`
- `codex plugin add PLUGIN@MARKETPLACE`
- `codex plugin list`

## Using Workpad from Codex Projects

The `workpad` skill should remain inside the `g4b_ai` plugin:

```text
plugins/g4b_ai/skills/workpad/SKILL.md
```

For any Codex project that wants to use it, install and enable `g4b_ai@reliquary`, then add project-level `AGENTS.md` instructions similar to:

```md
# Project Instructions

Working documents live in `docs/workpad/`.

Use the `g4b_ai:workpad` skill for plans, research notes, specs, journals, reports, goals, and brainstorms.
```

This gives Codex both pieces it needs:

- the installed plugin supplies the actual `workpad` skill
- `AGENTS.md` supplies the project-specific workpad location and policy

For projects that do not already have `docs/workpad/`, the workpad skill can decide placement using its own rules. In this repository, `docs/workpad/` already exists and should remain the canonical location.

## Recommended Changes to Reliquary

1. Add `.agents/plugins/marketplace.json`.
2. Add `.codex-plugin/plugin.json` to each plugin directory.
3. Update the root `README.md` with separate Claude and Codex installation sections.
4. Add a short `AGENTS.md` at the repo root for Codex-specific repo instructions, mirroring the important parts of `CLAUDE.md`.
5. Add a validation note or script so marketplace updates keep Claude and Codex plugin lists in sync.

The Codex marketplace should include all plugins currently listed in `.claude-plugin/marketplace.json`: `g4b_ai`, `dioxus`, `project-uv`, and `gitea`.

## Compatibility Notes

Codex can currently consume the Claude marketplace layout in this environment, but that is an implementation detail from the user's perspective. The repo should publish Codex-native metadata so future Codex versions, Codex app UI flows, and third-party tooling can rely on the expected Codex structure.

Codex plugin cache behavior is version-sensitive. During local plugin development, Codex's own update guidance recommends changing the plugin version with a Codex cachebuster suffix, reinstalling the plugin, and starting a new thread so the new skills and tools are loaded.

## Sources

- OpenAI Codex plugin creator skill: https://github.com/openai/codex/blob/main/codex-rs/skills/src/assets/samples/plugin-creator/SKILL.md
- OpenAI Codex plugin and marketplace JSON reference: https://raw.githubusercontent.com/openai/codex/main/codex-rs/skills/src/assets/samples/plugin-creator/references/plugin-json-spec.md
- OpenAI Codex local plugin update reference: https://raw.githubusercontent.com/openai/codex/main/codex-rs/skills/src/assets/samples/plugin-creator/references/installing-and-updating.md
- Local verification in this repo with Codex CLI 0.135.0-alpha.1.