cc-plugin-to-codex 0.1.0

Bridge Claude Code marketplace plugins into Codex (skills + subagents)

cc-plugin-to-codex

Bridge Claude Code marketplace plugins into Codex. Every source plugin becomes a cc-<name> Codex bridge, CC agent Markdown files are converted into Codex TOML agents, and everything is marked with an x-cc-bridge tag so list, update, and uninstall can cleanly manage them later.

Features

• Multi-source: accept a Git URL or a local marketplace checkout; interactive mode can also scan ~/.claude/plugins/marketplaces/ for every local market.
• Dual scope: install either globally (~/.codex/, ~/.agents/) or per project ($PWD/.codex/, $PWD/.agents/).
• Atomic swap: each plugin is staged in a sibling temp directory and swapped in with a POSIX rename, so a crash mid-sync leaves no half-written state.
• Dual-mode CLI:
  • TTY: questionary-driven selectors for source, plugins, scope, bridges.
  • Non-TTY / --yes / --json / --non-interactive: strict mode — missing required flags fail loudly instead of hanging.
• Safe re-sync: stale agents removed automatically; switching source on the same bridge is refused unless --force.
• Hands-off marker: user-authored plugins / agents without x-cc-bridge are never touched.

Installation

uvx (recommended, zero install)

uv ships with a one-shot runner:

uvx --from cc-plugin-to-codex cc2codex --help

Every invocation grabs the latest released version from PyPI. Add a shell alias if you use it often:

alias cc2codex='uvx --from cc-plugin-to-codex cc2codex'

uv tool install (persistent)

uv tool install cc-plugin-to-codex
cc2codex --help

Upgrade later with:

uv tool upgrade cc-plugin-to-codex

Plain pip

pip install cc-plugin-to-codex
cc2codex --help

Commands

Command	Purpose
cc2codex plugin-browse	List plugins exposed by a source marketplace. Read-only.
cc2codex plugin-sync	Install bridge plugins (skills + subagents) into Codex.
cc2codex plugin-list	Show installed bridges and their scope paths.
cc2codex plugin-update	Re-sync a bridge from the source recorded in its marker.
cc2codex plugin-uninstall	Remove bridge plugins by x-cc-bridge marker.

Each command supports --help for the full flag reference.

Asking an AI to drive cc2codex

A ready-made, agent-optimized skill file lives at skills/cc2codex/SKILL.md. It is written in the format Claude / Codex agents consume (frontmatter trigger + full flag / schema reference / strict-mode rules / pitfalls).

If you want an AI assistant — inside Claude Code, Codex, or any chat tool that can read a URL — to operate cc2codex for you, paste the raw URL above into the conversation and tell it "read this before you run any cc2codex command". The assistant will then know which flags are mandatory in non-interactive mode, how the x-cc-bridge marker semantics work, and the post-install Codex restart step users frequently forget.

Quick start

Browse a marketplace:

cc2codex plugin-browse --source https://github.com/your-org/your-cc-marketplace.git

Sync specific plugins to the global Codex scope:

cc2codex plugin-sync \
  --source https://github.com/your-org/your-cc-marketplace.git \
  --plugin ios-dev --plugin base \
  --scope global \
  --yes

Sync every plugin to the current project:

cc2codex plugin-sync \
  --source /path/to/local/cc-marketplace \
  --all-plugins --scope project \
  --yes

AI / scripting flow — full JSON output, no prompts:

cc2codex plugin-sync \
  --source <url> --all-plugins --scope global \
  --non-interactive --json

List, update, remove:

cc2codex plugin-list
cc2codex plugin-update --all --scope global --yes
cc2codex plugin-uninstall cc-ios-dev --scope global --yes

Codex needs one manual step after plugin-sync

Codex does not hot-reload ~/.agents/plugins/marketplace.json. After the first plugin-sync, restart Codex (or open a new session) and run /plugins to install the bridge from the "CC Bridged Plugins" marketplace. Until then Codex will not load the skills and agents.

How it works

For each selected plugin, plugin-sync:

1. Resolves the source (Git clone into /tmp, or reads the local path).
2. Copies the plugin directory to cc-<name>/, blacklisting CC-only mechanisms (hooks/, commands/, agents/, .claude-plugin/) and VCS/build noise (__pycache__, .git, .DS_Store, …). Skills, scripts, assets, and docs survive.
3. Writes .codex-plugin/plugin.json with the x-cc-bridge marker (source URL, ref, commit SHA, synced timestamp, agent list, …).
4. Converts every agents/*.md to a cc_<plugin>_<agent>.toml under ~/.codex/agents/, prefixing each file with a # x-cc-bridge: {…} comment so later runs recognise them as tool-generated.
5. Upserts the entry into marketplace.json with policy.installation = INSTALLED_BY_DEFAULT.

Re-syncing the same source compares the old marker's agents list with the new one and unlinks stale bridge agents; hand-authored TOMLs never match the marker and are kept.

Development

git clone https://github.com/ProAlexUSC/cc-plugin-to-codex
cd cc-plugin-to-codex
uv sync --extra dev
uv run pytest -v

CI runs the same pytest across Python 3.11 / 3.12 / 3.13 on Ubuntu and macOS.

Releasing

1. Bump version in pyproject.toml and update CHANGELOG.md.
2. Commit and tag: git tag v0.X.Y && git push origin v0.X.Y.
3. The Publish to PyPI workflow builds the wheel + sdist and uploads them via PyPI Trusted Publishing. Configure the trusted publisher once on PyPI with workflow = publish.yml and environment = pypi.

License

MIT.