ProAlexUSC/cc-plugin-to-codex

cc2codex

CLI, das CC-Marktplatz-Plugins in Codex synchronisiert. Jedes Quell-Plugin wird zu einer cc-<Name>-Bridge, CC-Agenten-Markdown wird in Codex-TOML konvertiert und jedes Artefakt wird mit einem x-cc-bridge-Marker versehen, sodass Liste / Update / Deinstallieren sie im Bulk verwalten können.

Installation

Das Paket ist auf PyPI veröffentlicht. Wähle eine dieser Aufrufmethoden – die Beispiele unten ehmen an, dass cc2codex auf $PATH ist:

1. uvx Zero-Install (empfohlen, immer aktuell):

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

2. uv tool install (dauerhaft):

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

3. Reines pip:

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

5 Befehle

Befehl	Beschreibung
plugin-browse	Nur-Lese-Liste der von einem Quellmarktplatz bereitgestellten Plugins
plugin-sync	Eine Bridge installieren: Dateien kopieren + Agenten konvertieren + Registry aktualisieren
plugin-list	Installierte Bridges anzeigen (identifiziert durch x-cc-bridge-Marker)
plugin-update	Aus dem im Marker gespeicherten Quell erneut synchronisieren
plugin-uninstall	Eine Bridge per Marker entfernen

Kernkonzepte

• Bereich: global = ~/.codex/ ~/.agents/; project = $PWD/.codex/ $PWD/.agents/. --scope ist im strikten Modus erforderlich.
• Quelle: eine Git-URL (git@host:org/repo.git, https://…/repo.git, ssh://…, git://… oder bloßes git@host:path) oder ein lokaler Checkout-Pfad, der .claude-plugin/marketplace.json enthält. Git-Quellen werden nach /tmp geklont und danach bereinigt. --ref akzeptiert einen Branch, Tag oder Commit-SHA.
• x-cc-bridge-Marker: Top-Level-Feld in einem Bridge-plugin.json plus ein Erstzeilen-Kommentar in jedem Bridge-Agent-TOML. Dateien ohne den Marker sind benutzererstellt und das Tool überschreibt sie nie, es sei denn, --force wird übergeben.
• Namensgebung: Bridge-Name ist cc-<Quell-Plugin>; Agent-TOML-Dateiname ist cc_<Plugin-Snake>_<Agent-Snake>.toml (Kebab-Case → Snake-Case).

Typische Abläufe

Ein oder alle Plugins synchronisieren (KI-freundlich)

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

# Alles
cc2codex plugin-sync \
  --source /path/to/cc-marketplace \
  --all-plugins --scope global \
  --non-interactive --yes

Das erneute Synchronisieren derselben Quelle ist sicher: Agenten, die im alten Marker vorhanden waren, aber nicht mehr in der Quelle vorhanden sind, werden automatisch bereinigt.

⚠️ Nach plugin-sync muss der Benutzer die Bridge in Codex installieren

Codex lädt ~/.agents/plugins/marketplace.json nicht neu. Sobald cc2codex die Dateien geschrieben hat, muss der Benutzer Codex neu starten (oder eine neue Sitzung starten), /plugins ausführen, die neu hinzugefügte Bridge im Marktplatz "CC Bridged Plugins" auswählen und installieren. Bis dieser Installationsschritt ausgeführt wird, lädt Codex die Skills und Agenten nicht. Bei der Erklärung einer erfolgreichen Synchronisation sollte diese Anweisung immer folgen.

Zustand prüfen

cc2codex plugin-list                       # menschlicher Text
cc2codex plugin-list --scope global --json # maschinenlesbar

Aktualisieren

cc2codex plugin-update cc-ios-dev --scope global --non-interactive --yes
cc2codex plugin-update --all --non-interactive --yes

--source muss nicht erneut übergeben werden – das Tool liest es aus dem Marker.

Deinstallieren

cc2codex plugin-uninstall cc-ios-dev --scope global --non-interactive --yes
cc2codex plugin-uninstall --all --scope all --non-interactive --yes

Entfernt das Plugin-Verzeichnis + jeden zugehörigen Agenten-TOML + den Registry-Eintrag.

⚠️ Codex hat seinen eigenen Cache; die Deinstallation deckt nur die Hälfte ab

cc2codex entfernt nur die von ihm geschriebenen Dateien. Codex hat zwei zusätzliche"> Statusorte, die cc2codex nicht berühren kann:

• ~/.codex/plugins/cache/cc-bridged-plugins/<bridge>/<version>/ – Codex kopiert Bridges hierher, wenn der Benutzer /plugins install ausführt, und lädt von hier zur Laufzeit.
• ~/.codex/config.toml, Abschnitt [plugins."<bridge>@cc-bridged-plugins"] enabled = true – Codexs eigener Aktivierungsstatus.

Daher wird eine Bridge, die zuvor in Codex installiert wurde, nach einer cc2codex-Deinstallation immer noch aus dem Cache geladen. Nach der Erklärung, dass die Deinstallation erfolgreich war, weise den Benutzer auch an, /plugins in Codex auszuführen und dieselbe Bridge dort zu deinstallieren, damit Codex seinen eigenen Cache + Konfiguration bereinigen kann.

Oder manuell: rm -rf ~/.codex/plugins/cache/cc-bridged-plugins/<bridge> und bearbeite ~/.codex/config.toml, um den passenden Abschnitt [plugins."…"] zu entfernen.

Regeln des strikten Modus (wichtig)

Wenn kein TTY vorhanden ist oder eines von --yes / --json / --non-interactive übergeben wird, läuft der Befehl im strikten Modus. Im strikten Modus muss jede Entscheidung explizit angegeben werden:

Fehlendes Element	Fehlermeldung
--source	source not specified; pass --source <git-url-or-path>
--plugin oder --all-plugins	no plugins selected; pass --plugin <name> (repeatable) or --all-plugins
--scope	`scope not specified; pass --scope global
uninstall/update ohne Namen oder --all	must specify a bridge name or --all to X (installed: …)

Beim Aufruf über eine KI oder ein Skript alle Flags von vornherein übergeben – sich nicht auf Standardwerte verlassen.

Interaktiver Modus

In einem echten TTY öffnet das Weglassen eines Flags einen questionary-Selektor:

• Quelltyp: Git-URL / Lokaler Pfad / ~/.claude/plugins/marketplaces/ scannen
• Plugins: Mehrfachauswahl-Checkbox
• Bereich: global / project
• uninstall / update-Bridge-Ziel: Mehrfachauswahl-Checkbox

Häufige Fallstricke

1. Nicht-Bridge-Konflikt: Ein Plugin-Verzeichnis existiert bereits am Zielpfad, hat aber keinen x-cc-bridge-Marker → abgelehnt (schützt benutzererstellte Inhalte). Übergib --force zum Überschreiben.
2. Quellwechsel-Konflikt: Eine Bridge mit demselben Namen wurde zuvor von Quelle A synchronisiert und jetzt zeigst du auf Quelle B → abgelehnt. Führe zuerst plugin-uninstall aus oder übergib --force.
3. Plugin-Name vs. Bridge-Name: --plugin nimmt den Quell-Namen (z. B. ios-dev), nicht den Bridge-Namen (cc-ios-dev). Das Positionsargument von plugin-uninstall / plugin-update nimmt den Bridge-Namen.
4. Registry-Richtlinie: Jeder Registry-Eintrag wird mit installation: INSTALLED_BY_DEFAULT + authentication: ON_USE geschrieben, damit Codex die Bridge automatisch aktiviert, sobald sie installiert ist.
5. Bereinigung veralteter Agenten ist sicher: Nur TOMLs, die den x-cc-bridge -Kommentar tragen, werden jemals gelöscht; handgeschriebene TOMLs bleiben unberührt.

---

Vollständige Flag-Referenz

Gemeinsame Flags

Flag	Bedeutung
--source <url-or-path>	Git-URL (git@host:org/repo.git, https://…/repo.git) oder lokaler Pfad (Verzeichnis mit .claude-plugin/marketplace.json). Zum interaktiven Auswählen weglassen.
`--ref <branch	tag
--scope {global,project}	Zielbereich. global → ~/.codex/ ~/.agents/; project → $PWD/.codex/ $PWD/.agents/. Im strikten Modus für plugin-sync erforderlich.
--scope {global,project,all}	Bereichsfilter für plugin-list, plugin-update, plugin-uninstall. Standardmäßig all.
--plugin <name>	Wiederholbar. Nimmt den quellseitigen Plugin-Namen (kein cc--Präfix). Schließt sich gegenseitig mit --all-plugins aus.
--all-plugins	Jedes vom Quell bereitgestellte Plugin synchronisieren.
--all	plugin-update / plugin-uninstall auf jede Bridge im Zielbereich anwenden.
--yes	Bestätigungsaufforderungen überspringen (impliziert strikt).
--non-interactive	Strikten Modus erzwingen; automatisch aktiviert, wenn stdin kein TTY ist.
--force	Konfliktschutz umgehen (Nicht-Bridge-Überschreibung, andere Quelle).
--json	Maschinenlesbares JSON auf stdout ausgeben (impliziert strikt).

plugin-browse

Nur-Lese-Liste der Plugins in einem Quellmarktplatz. Schreibt nichts.

cc2codex plugin-browse --source <url-or-path> [--ref <ref>] [--json]

Nicht-interaktiv: --source ist erforderlich.

plugin-sync

Hauptinstallationsbefehl. Pipeline:

1. Quelle auflösen (Git-Klon nach /tmp oder lokalen Pfad lesen).
2. <source>/.claude-plugin/marketplace.json lesen, um verfügbare Plugins aufzulisten.
3. Mit --plugin / --all-plugins filtern.
4. Für jedes ausgewählte Plugin:
   • Jedes agents/*.md vorab konvertieren (bei Fehler sofort abbrechen).
   • Auf Agent-TOML-Konflikte prüfen (benutzererstellt → ablehnen, es sei denn --force).
   • Ein paralleles Verzeichnis einrichten und kopieren (Blacklist schließt .claude-plugin/, .codex-plugin/, hooks/, commands/, agents/, VCS/Build-Rauschen aus).
   • .codex-plugin/plugin.json inklusive des x-cc-bridge-Markers und der endgültigen Agentenliste schreiben.
   • Atomares POSIX-Rename des bereitgestellten Verzeichnisses über die alte Bridge.
   • Agent-TOMLs schreiben (# x-cc-bridge: {…}-Kommentar in Zeile 1).
   • Veraltete Agenten entfernen (im alten Marker, aber nicht in der neuen Liste).
   • Den marketplace.json-Eintrag aktualisieren (policy.installation = INSTALLED_BY_DEFAULT).

cc2codex plugin-sync \
  --source <url-or-path> [--ref <ref>] \
  --scope {global|project} \
  {--plugin <name> [--plugin <name>] … | --all-plugins} \
  [--force] [--yes] [--non-interactive] [--json]

Nicht-interaktiv: --source, --scope und --plugin|--all-plugins sind alle erforderlich.

plugin-list

Jedes Plugin-Verzeichnis im Zielbereich scannen und diejenigen auflisten, die einen x-cc-bridge-Marker tragen.

cc2codex plugin-list [--scope {global|project|all}] [--json]

Im Textmodus werden die Pfade pluginsDir / agentsDir / registry für jeden Bereich gefolgt vom Bridge-Inventar mit Agentennamen ausgegeben. Der JSON-Modus gruppiert dieselben Daten nach Bereich.

plugin-update

x-cc-bridge.source + .ref der Bridge verwenden, um die Quelle erneut aufzulösen und die Synchronisationspipeline auszuführen. Quell-Argumente sind NICHT erneut erforderlich.

cc2codex plugin-update [cc-<name> | --all] \
  [--scope {global|project|all}] \
  [--force] [--yes] [--non-interactive] [--json]

• Das Positionsargument ist der Bridge-Name (mit cc--Präfix).
• --all aktualisiert jede Bridge im Zielbereich.
• Im strikten Modus löst ein fehlender Name / --all einen Fehler aus, der die installierten Bridges auflistet.

plugin-uninstall

Bereinigung, gesteuert durch x-cc-bridge.agents. Nur Dateien mit dem Marker werden entfernt; benutzererstellte Plugins und Agenten sind immer sicher.

cc2codex plugin-uninstall [cc-<name> | --all] \
  [--scope {global|project|all}] \
  [--yes] [--non-interactive] [--json]

Löschreihenfolge:

1. Jeder unter x-cc-bridge.agents aufgeführte Agent-TOML.
2. Das Verzeichnis scope.plugins_dir/cc-<name>/ selbst.
3. Der Eintrag in scope.registry (das plugins[]-Array von marketplace.json).

Die Datei marketplace.json selbst wird nie entfernt, selbst wenn das Array leer ist (plugins: []).

JSON-Schemas

plugin-browse --json

{
  "marketplace": {
    "name": "<string>",
    "source": "<string>",
    "sourceKind": "git|local",
    "ref": "<string or null>",
    "commit": "<string>"
  },
  "plugins": [
    {
      "name": "<string>",
      "version": "<string>",
      "description": "<string>",
      "skillCount": 0,
      "agentCount": 0,
      "hasCodexManifest": true
    }
  ]
}

plugin-sync --json

{
  "scope": "global|project",
  "synced": [
    {
      "bridgeName": "cc-<name>",
      "bridgeDir": "<absolute path>",
      "agents": ["cc_<plugin>_<agent>", "..."]
    }
  ]
}

plugin-list --json

{
  "scopes": {
    "global": {
      "pluginsDir": "<path>",
      "agentsDir": "<path>",
      "registry": "<path>",
      "bridges": [
        {
          "name": "cc-<name>",
          "version": "<string>",
          "sourcePlugin": "<source name>",
          "source": "<url-or-path>",
          "sourceKind": "git|local",
          "ref": "<string or null>",
          "commit": "<sha or 'local'>",
          "marketplace": "<source market name>",
          "syncedAt": "<ISO-8601 UTC>",
          "agents": ["cc_<plugin>_<agent>", "..."]
        }
      ]
    },
    "project": { "...": "same shape" }
  }
}

plugin-update --json

{
  "updated": [
    {"bridgeName": "cc-<name>", "commit": "<sha>", "scope": "global|project"}
  ]
}

plugin-uninstall --json

{
  "removed": [
    {"bridge": "cc-<name>", "agents": ["cc_<plugin>_<agent>", "..."], "scope": "global|project"}
  ]
}

Exit-Codes

Code	Bedeutung
0	Erfolg
1	Laufzeitfehler (Bridge nicht gefunden, ungelöster Konflikt, SyncConflictError, …)
2	Fehlende / ungültige Argumente (strikter Modus, unbekannter Plugin-Name, …)

x-cc-bridge-Marker-Format

Geschrieben auf der obersten Ebene von <scope.plugins_dir>/cc-<name>/.codex-plugin/plugin.json:

{
  "x-cc-bridge": {
    "sourcePlugin": "<source name without cc- prefix>",
    "source": "<url or absolute path>",
    "sourceKind": "git|local",
    "ref": "<branch/tag/sha or null>",
    "commit": "<sha or 'local'>",
    "marketplace": "<name from source marketplace.json>",
    "syncedAt": "<ISO-8601 UTC>",
    "tool": "cc-plugin-to-codex/<version>",
    "agents": ["cc_<plugin>_<agent>", "..."]
  }
}

Erstzeilen-Kommentar in jedem Bridge-Agent-TOML:

# x-cc-bridge: {"sourcePlugin":"<name>","sourceAgent":"<original-name>","bridgePlugin":"cc-<name>","syncedAt":"..."}
name = "cc_<plugin>_<agent>"
description = "..."
developer_instructions = """..."""

Erkennungsregeln:

• Eine plugin.json ist eine Bridge, wenn sie ein Top-Level-Wörterbuch x-cc-bridge hat.
• Ein Agent-TOML ist eine Bridge, wenn seine erste Zeile mit dem Regex ^# x-cc-bridge: (\{.*\})$ übereinstimmt, das JSON-Payload geparst wird und die vier erforderlichen Schlüssel vorhanden sind.

Alles ohne Übereinstimmung wird als benutzererstellt behandelt; das Tool lässt es in Ruhe. --force ist die einzige Möglichkeit, dies zu überschreiben.