cc-to-codex

Convert Claude Code Plugin → Codex

Convert a single plugin from Claude Code format to Codex-compatible format.

When to activate

• User says "convert X to Codex", "port X to Codex", "add Codex support for X"
• User provides a path like plugins/obsidian-tracker or just a plugin name

Inputs

• Plugin path — relative to repo root, e.g. plugins/obsidian-tracker
• Repo root — directory containing .claude-plugin/marketplace.json (default: detect from cwd)

Workflow

Phase 0: Vendor external plugins

When the plugin lives outside this repository, copy it into plugins_dir before conversion. Review license and attribution, resolve name collisions, discard stale foreign generated artifacts after review, and explicitly choose the source of truth when attaching. Deterministic scripts never copy files between repositories.

Step 1 — Read source

Read the following files from the target plugin (skip if absent):

1. <plugin-path>/.claude-plugin/plugin.json — required
2. <plugin-path>/.mcp.json — optional
3. <plugin-path>/skills/ directory listing — optional
4. <plugin-path>/commands/ directory listing — optional
5. <plugin-path>/agents/ directory listing — optional
6. <plugin-path>/README.md — optional

If .claude-plugin/plugin.json is missing, stop and report: "Not a Claude Code plugin: no .claude-plugin/plugin.json found."

Step 2 — Check for existing Codex manifest

If <plugin-path>/.codex-plugin/plugin.json already exists, read it and note what's already generated. Ask the user:

".codex-plugin/plugin.json already exists. Overwrite or merge?"

Step 3 — Generate .codex-plugin/plugin.json

Build the Codex manifest from the source Claude manifest:

{
  "name": "<same as CC name>",
  "version": "<same version>",
  "description": "<same description>",
  "author": {
    "name": "<author.name from CC>"
  },
  "skills": "./skills/",
  "interface": {
    "displayName": "<Title Case of plugin name>",
    "shortDescription": "<first sentence of description, max 80 chars>",
    "developerName": "<author.name>",
    "category": "Development",
    "capabilities": ["Read", "Write"]
  }
}