cc2codex

CC マーケットプレイスのプラグインを Codex に同期する CLI。各ソースプラグインは cc-<name> ブリッジとなり、CC エージェント Markdown は Codex TOML に変換され、すべての生成物には x-cc-bridge マーカーが付与されるため、一覧表示 / 更新 / アンインストールを一括管理できます。

インストール

このパッケージは PyPI で公開されています。以下の呼び出し形式から選択してください。以下の例では cc2codex が $PATH 上にあるものとします。

uvx ゼロインストール（推奨、常に最新）:
```
uvx --from cc-plugin-to-codex cc2codex --help
```

uv tool install（永続的）:

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

通常の pip:

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

5 つのコマンド

コマンド	機能
`plugin-browse`	ソースマーケットプレイスが公開するプラグインを読み取り専用で一覧表示
`plugin-sync`	ブリッジをインストール：ファイルをコピー + エージェントを変換 + レジストリを更新
`plugin-list`	インストール済みブリッジを表示（`x-cc-bridge` マーカーで識別）
`plugin-update`	マーカーに記録されたソースから再同期
`plugin-uninstall`	マーカーによってブリッジを削除

コアコンセプト

スコープ: global = ~/.codex/ ~/.agents/; project = $PWD/.codex/ $PWD/.agents/。厳格モードでは --scope が必須です。
ソース: Git URL（git@host:org/repo.git、https://…/repo.git、ssh://…、 git://…、または bare git@host:path）または .claude-plugin/marketplace.json を含むローカルチェックアウトパス。 Git ソースは /tmp にクローンされ、後にクリーンアップされます。--ref はブランチ、タグ、コミット SHA を受け付けます。
x-cc-bridge マーカー: ブリッジ plugin.json のトップレベルフィールド、および各ブリッジエージェント TOML の先頭行コメント。マーカーのないファイルはユーザー作成とみなされ、--force が指定されない限り上書きされません。
命名規則: ブリッジ名は cc-<source-plugin>。エージェント TOML ファイル名は cc_<plugin_snake>_<agent_snake>.toml（ケバブケース → スネークケース）。

典型的なフロー

1 つまたはすべてのプラグインを同期（AI 向け）

# 特定のプラグイン
cc2codex plugin-sync \
  --source https://github.com/your-org/cc-marketplace.git \
  --plugin ios-dev --plugin base \
  --scope global \
  --non-interactive --yes

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

同じソースの再同期は安全です。古いマーカーに存在したがソースに存在しなくなったエージェントは自動的にクリーンアップされます。

⚠️ plugin-sync 後、ユーザーは Codex 内でブリッジをインストールする必要があります

Codex は ~/.agents/plugins/marketplace.json をホットリロードしません。cc2codex がファイルの書き込みを完了したら、ユーザーは Codex を再起動（または新しいセッションを開始）し、/plugins を実行し、新しく追加されたブリッジを「CC Bridged Plugins」マーケットプレイスで選択してインストールする必要があります。このインストール手順が実行されるまで、Codex はスキルとエージェントをロードしません。同期が成功したことを説明する際は、必ずこの指示をフォローアップしてください。

状態確認

cc2codex plugin-list                       # 人間可読テキスト
cc2codex plugin-list --scope global --json # 機械可読 JSON

更新

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

再度 --source を指定する必要はありません。ツールがマーカーから読み取ります。

アンインストール

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

プラグインディレクトリと、関連するすべてのエージェント TOML、レジストリエントリを削除します。

⚠️ Codex には独自のキャッシュがあります。アンインストールは片方だけです

cc2codex は自身が書き込んだファイルのみを削除します。Codex には cc2codex が触れられない 2 つの追加状態の場所 があります:

~/.codex/plugins/cache/cc-bridged-plugins/<bridge>/<version>/ — ユーザーが /plugins install を実行すると Codex がブリッジをここにコピーし、ランタイム時にここから読み込みます。

~/.codex/config.toml のセクション [plugins."<bridge>@cc-bridged-plugins"] enabled = true — Codex 自身の有効状態。

その結果、以前 Codex 内でインストールされたブリッジは、cc2codex のアンインストール後もキャッシュからロードされ続けます。アンインストールが成功したことを説明した後、ユーザーに Codex 内で /plugins を実行し、同じブリッジをそこでアンインストールするように指示してください。これにより Codex が自身のキャッシュと設定をクリーンアップできます。

または手動で: rm -rf ~/.codex/plugins/cache/cc-bridged-plugins/<bridge> を実行し、~/.codex/config.toml を編集して該当する [plugins."…"] セクションを削除してください。

厳格モードのルール（重要）

TTY がない場合、または --yes / --json / --non-interactive のいずれかが指定された場合、コマンドは 厳格モード で実行されます。厳格モードでは、すべての決定を明示的に指定する必要があります:

不足しているもの	エラーメッセージ
`--source`	`source not specified; pass --source <git-url-or-path>`
`--plugin` または `--all-plugins`	`no plugins selected; pass --plugin <name> (repeatable) or --all-plugins`
`--scope`	`scope not specified; pass --scope global
`uninstall`/`update` に名前または `--all` がない	`must specify a bridge name or --all to X (installed: …)`

AI やスクリプトから呼び出す場合は、すべてのフラグを事前に指定してください。デフォルトに依存しないでください。

インタラクティブモード

実際の TTY では、フラグを省略すると questionary のセレクターが表示されます:

ソースタイプ: Git URL / ローカルパス / ~/.claude/plugins/marketplaces/ をスキャン
プラグイン: 複数選択チェックボックス
スコープ: global / project
uninstall / update のブリッジターゲット: 複数選択チェックボックス

よくある落とし穴

非ブリッジとの競合: ターゲットパスにプラグインディレクトリは存在するが x-cc-bridge マーカーがない場合 → 拒否（ユーザー作成コンテンツを保護）。上書きするには --force を指定。
ソース切り替えの競合: 同じ名前のブリッジが以前ソース A から同期され、今ソース B を指定している場合 → 拒否。最初に plugin-uninstall を実行するか、--force を指定。
プラグイン名とブリッジ名: --plugin は ソース 名（例: ios-dev）を指定し、ブリッジ名（cc-ios-dev）ではありません。plugin-uninstall / plugin-update の位置引数は ブリッジ 名を指定します。
レジストリポリシー: 各レジストリエントリは installation: INSTALLED_BY_DEFAULT + authentication: ON_USE で書き込まれるため、Codex はブリッジを自動的に有効化します。
古いエージェントのクリーンアップは安全: x-cc-bridge コメントを持つ TOML のみが削除されます。手書きの TOML はそのまま残ります。

全フラグリファレンス

共有フラグ

フラグ	意味
`--source <url-or-path>`	Git URL（`git@host:org/repo.git`、`https://…/repo.git`）またはローカルパス（`.claude-plugin/marketplace.json` を含むディレクトリ）。省略するとインタラクティブに選択。
`--ref <branch	tag
`--scope {global,project}`	ターゲットスコープ。`global` → `~/.codex/ ~/.agents/`; `project` → `$PWD/.codex/ $PWD/.agents/`。`plugin-sync` では厳格モードで必須。
`--scope {global,project,all}`	`plugin-list`、`plugin-update`、`plugin-uninstall` のスコープフィルター。デフォルトは `all`。
`--plugin <name>`	繰り返し可能。ソース側のプラグイン名（`cc-` プレフィックスなし）を指定。`--all-plugins` と排他的。
`--all-plugins`	ソースが公開するすべてのプラグインを同期。
`--all`	`plugin-update` / `plugin-uninstall` をターゲットスコープ内のすべてのブリッジに適用。
`--yes`	確認プロンプトをスキップ（厳格モードを暗黙指定）。
`--non-interactive`	厳格モードを強制。stdin が TTY でない場合に自動的に有効。
`--force`	競合保護をバイパス（非ブリッジ上書き、異なるソース）。
`--json`	機械可読な JSON を標準出力に出力（厳格モードを暗黙指定）。

`plugin-browse`

ソースマーケットプレイス内のプラグインを読み取り専用で一覧表示。何も書き込みません。

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

非インタラクティブモード: --source が必須。

`plugin-sync`

コアインストールコマンド。パイプライン:

ソースを解決（Git クローンを /tmp に、またはローカルパスを読み取り）。
<source>/.claude-plugin/marketplace.json を読み取り、利用可能なプラグインを一覧表示。
--plugin / --all-plugins でフィルタリング。
選択された各プラグインについて:
- すべての agents/*.md を事前変換（問題があれば即時失敗）。
- エージェント TOML の競合をチェック（ユーザー作成 → --force 以外は拒否）。
- 兄弟ディレクトリをステージングし、コピー（ブラックリストで .claude-plugin/、.codex-plugin/、hooks/、commands/、agents/、VCS/ビルドノイズを除外）。
- x-cc-bridge マーカーと最終エージェントリストを含む .codex-plugin/plugin.json を書き込み。
- POSIX アトミックリネームでステージングディレクトリを古いブリッジに上書き。
- エージェント TOML（1行目に # x-cc-bridge: {…} コメント）を書き込み。
- 古いエージェント（古いマーカーにあるが新しいリストにないもの）を削除。
- marketplace.json エントリを upsert （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]

非インタラクティブモード: --source、--scope、--plugin|--all-plugins がすべて必須。

`plugin-list`

ターゲットスコープ内のすべてのプラグインディレクトリをスキャンし、x-cc-bridge マーカーを持つものを一覧表示。

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

テキストモードは各スコープの pluginsDir / agentsDir / registry パスを出力し、続けてエージェント名を含むブリッジ一覧を表示。JSON モードは同じデータをスコープ別にグループ化。

`plugin-update`

ブリッジの x-cc-bridge.source + .ref を使用してソースを再解決し、同期パイプラインを実行。ソース引数は再度必要ありません。

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

位置引数は ブリッジ 名（cc- プレフィックス付き）。
--all はターゲットスコープ内のすべてのブリッジを更新。
厳格モードでは、名前 / --all がない場合、インストール済みブリッジを一覧表示するエラーを出力。

`plugin-uninstall`

x-cc-bridge.agents に基づくクリーンアップ。マーカーを持つファイルのみが削除されます。ユーザー作成のプラグインとエージェントは常に安全です。

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

削除順序:

x-cc-bridge.agents にリストされているすべてのエージェント TOML。
scope.plugins_dir/cc-<name>/ ディレクトリ自体。
scope.registry 内のエントリ（marketplace.json の plugins[] 配列）。

marketplace.json ファイル自体はたとえ配列が空になっても削除されません（plugins: []）。

JSON スキーマ

`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"}
  ]
}

終了コード

コード	意味
`0`	成功
`1`	ランタイムエラー（ブリッジが見つからない、競合が解決できない、`SyncConflictError` など）
`2`	引数の欠落 / 不正（厳格モード、不明なプラグイン名など）

`x-cc-bridge` マーカーフォーマット

<scope.plugins_dir>/cc-<name>/.codex-plugin/plugin.json のトップレベルに書き込まれます:

{
  "x-cc-bridge": {
    "sourcePlugin": "<cc- プレフィックスなしのソース名>",
    "source": "<URL または絶対パス>",
    "sourceKind": "git|local",
    "ref": "<ブランチ/タグ/SHA または null>",
    "commit": "<SHA または 'local'>",
    "marketplace": "<ソース marketplace.json からの名前>",
    "syncedAt": "<ISO-8601 UTC>",
    "tool": "cc-plugin-to-codex/<バージョン>",
    "agents": ["cc_<plugin>_<agent>", "..."]
  }
}

各ブリッジエージェント TOML の先頭行コメント:

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

検出ルール:

plugin.json は、トップレベルに x-cc-bridge 辞書がある場合にブリッジとみなされます。
エージェント TOML は、最初の行が正規表現 ^# x-cc-bridge: (\{.*\})$ に一致し、JSON ペイロードがパースでき、4 つの必須キーが存在する場合にブリッジとみなされます。

一致しないものはすべてユーザー作成として扱われ、ツールはそれらに触れません。--force のみが上書きを許可します。

ProAlexUSC/cc-plugin-to-codex

cc-plugin-to-codex とは？

お気に入りのAIに質問する

ドキュメント

cc2codex

インストール

5 つのコマンド

コアコンセプト

典型的なフロー

1 つまたはすべてのプラグインを同期（AI 向け）

状態確認

更新

アンインストール

厳格モードのルール（重要）

インタラクティブモード

よくある落とし穴

全フラグリファレンス

共有フラグ

`plugin-browse`

`plugin-sync`

`plugin-list`

`plugin-update`

`plugin-uninstall`

JSON スキーマ

`plugin-browse --json`

`plugin-sync --json`

`plugin-list --json`

`plugin-update --json`

`plugin-uninstall --json`

終了コード

`x-cc-bridge` マーカーフォーマット

関連スキル

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep

お気に入りのAIに質問する

ドキュメント

cc2codex

インストール

5 つのコマンド

コアコンセプト

典型的なフロー

1 つまたはすべてのプラグインを同期（AI 向け）

状態確認

更新

アンインストール

厳格モードのルール（重要）

インタラクティブモード

よくある落とし穴

全フラグリファレンス

共有フラグ

plugin-browse

plugin-sync

plugin-list

plugin-update

plugin-uninstall

JSON スキーマ

plugin-browse --json

plugin-sync --json

plugin-list --json

plugin-update --json

plugin-uninstall --json

終了コード

x-cc-bridge マーカーフォーマット

関連スキル

steipete/bluebubbles

steipete/eightctl

steipete/blucli

steipete/bear-notes

steipete/camsnap

steipete/gifgrep

`plugin-browse`

`plugin-sync`

`plugin-list`

`plugin-update`

`plugin-uninstall`

`plugin-browse --json`

`plugin-sync --json`

`plugin-list --json`

`plugin-update --json`

`plugin-uninstall --json`

`x-cc-bridge` マーカーフォーマット