mcpField
C
codex-vision

codex-vision

github.com/thenamangoyalクリエイティブ・メディア049 回インストール16 週間前に更新
リポジトリ

codex-vision について

シェルラッパーを介して Claude から OpenAI Codex CLI を呼び出し、画像の確認、生成、編集を行うスキルです。用途別のモードがあり、確認セッションの継続にも対応します。

主な機能

  1. 01Codex による画像確認
  2. 02プロンプトからの画像生成
  3. 03既存画像ファイルの編集
  4. 04画像確認セッションの再開
  5. 05出力先とモデルの指定

活用シーン

  1. 01Codex にスクリーンショットを確認させる
  2. 02モックアップやワイヤーフレームを生成
  3. 03画像の修正や注釈追加
  4. 04更新した画像を再度レビュー

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/thenamangoyal/codex-vision --skill codex-vision

インストール後、Claude Code で/codex-visionを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.gitignore
LICENSE
CHANGELOG.md
README.md
scripts/
check-triggering.sh
codex-vision.sh
tests/
test_select_image.sh
test_rollout_extract.sh
tests/quoting/
check-quoting.sh
tests/session-modes/
check-session-modes.sh
tests/triggering/
cases.yaml

詳細

codex-vision

画像入力、画像生成、画像編集などのビジョンタスク向けに、OpenAI Codex CLI（アップストリームのバイナリ /Applications/Codex.app/Contents/Resources/codex）をラップします。Claude は一時ファイルを手動で書き出したり、その都度シェルを直接呼び出したりせずに Codex を呼び出せます。

このスキルを呼び出すタイミング

該当する条件は 2 通りあります。

A. 明示的な呼び出し — 無条件で起動します。 use codex-vision、/codex-vision、またはラッパーを直接シェルから呼び出す記述がある場合です。画像のコンテキストは必要ありません（ユーザーが意図的にスキルを指定しているためです）。

B. 画像に関する意図を示すトリガー — 画像のコンテキストと Codex を使う意図の両方が必要です。 画像のコンテキストとは、既存の画像パスまたは添付ファイル（PNG、JPG、JPEG、WebP、GIF）、ユーザーが今まさに言及している新たに作成したスクリーンショット、またはビジュアル成果物（モックアップ、ワイヤーフレーム、デザイン画像）の生成・編集を明示的に求めることです。「codex」という単語だけでは不十分です。対象ファイルがない状態での「screenshot」だけでも不十分です。

  • ユーザーが特定のスクリーンショットまたはディスク上の PNG/JPG パスを Codex に見てもらうよう Claude に依頼する → review。
  • ユーザーが Codex に画像／モックアップ／ワイヤーフレーム／デバイスフレームのレンダリングを生成するよう依頼する（Codex を使う意図が明示されている必要があります。「モックを生成して」だけの場合は、ほかのツールに振り分けます） → generate。
  • ユーザーが Codex に既存の画像ファイルを編集／注釈付け／クリーンアップするよう依頼する（パスが必要です） → edit。
  • スクリーンショットが作成された直後（例：mcp__claude-in-chrome__computer が save_to_disk: true で保存）かつ、ユーザーがその画像を Codex 側でレビューするよう明示的に依頼している場合。スクリーンショットの後に行う Codex のタスクなら何でもよいわけではありません。

このスキルを呼び出さないタイミング

次の場合は、通常の codex exec または永続的な Codex セッションスキルを優先してください。

  • ユーザーが Codex にコード、PR、差分、関数のレビューを依頼する — テキストのみで、画像はありません。-i フラグは関係ありません。
  • ユーザーが Codex にコードの作成、リファクタリング、デバッグを依頼する — codex exec "<prompt>" を直接呼び出してください。
  • ユーザーが画像を添付せずに Codex に一般的な質問（「X についてどう思うか Codex に聞いて」「Y を Codex に説明してもらって」など）をする。
  • ユーザーが Codex との長時間のリポジトリコーディングセッションを希望している。特にスクリーンショットを基に実装を繰り返す場合は、インストール済みの永続的な Codex/tmux ワークフローを使ってください。同じリポジトリスコープの Codex セッションでレビュー、実装、テストを行い、再開できます。
  • ユーザーが「codex」と言及していても、実際の成果物がテキスト（ログ、スタックトレース、JSON、コード）の場合 — codex-vision を使っても意味がありません。image_gen ツールをプロンプトすると、モデルを誤った方向に誘導してしまいます。
  • ユーザーがディスク上にスクリーンショットを持っていても、現在の依頼がそのスクリーンショットと無関係な場合 — /tmp/ に PNG が存在するというだけで自動的に起動しないでください。

ユーザーの意図が曖昧な場合（「Codex、私の成果物を見て」など）は、どちらの方法も呼び出す前に、成果物が画像かテキストかを確認してください。

呼び出し方

このスキルは単一のシェルラッパーです。Bash ツールから実行します。

~/.claude/skills/codex-vision/scripts/codex-vision.sh <mode> [options] <args>

長時間の画像作業

永続的なリポジトリ作業には、このスキルの --tmux モードを使わないでください。このモードは、1 回限りの codex exec 呼び出しを監視するラッパーにすぎません。

「このダッシュボードのスクリーンショットを使って、ページを再設計し、コードを実装してテストし、後で作業を続ける」といったタスクでは、codex-vision ではなく、インストール済みの永続的な Codex/tmux ワークフローを使ってください。このワークフローでは、リポジトリスコープの Codex UUID が維持され、画像を繰り返し添付でき、入出力画像がリポジトリ内の .agent/codex/images/ の受け渡し領域に保存されます。

成果物の保存

このスキルは意図的に一時的な単発処理として設計されています。codex-vision からリポジトリ内に .agent/codex/ ツリーを作成または管理しないでください。

  • 入力画像は呼び出し側が指定するパスから読み取ります。呼び出し側から URL が渡された場合は、まず /tmp/ にダウンロードしてください。
  • 生成・編集した画像は、デフォルトで /tmp/codex-vision-out/<slug>-<timestamp>.png に保存されます。
  • tmux の監視ログは、デフォルトで /tmp/claude-codex-<slug>.log に保存されます。

ユーザーがリポジトリ内での永続的な画像履歴、スクリーンショットの繰り返し保存、または実装作業に関連付けられた生成アセットを希望する場合は、永続的な Codex/tmux ワークフローに振り分けてください。

モード
モード概要動作
review IMAGE [IMAGE...] PROMPT1 回限りの画像レビューcodex exec -i ... を実行します
generate PROMPTCodex に画像の生成を依頼しますプロンプトを「Use image_gen to ; save to 」としてラップします
edit IMAGE PROMPTCodex に画像の編集を依頼しますプロンプトを「Use image_gen to edit the attached image: ...」としてラップします
オプション
オプション効果
--out PATH生成／編集した画像の出力先（デフォルト：/tmp/codex-vision-out/<slug>-<ts>.png）
--tmux NAMEclaude-codex-<NAME> tmux セッション内で実行します。ユーザーは tmux attach -t claude-codex-<NAME> でライブ状況を確認できます
--keep完了後も tmux セッションとログを残します（デフォルトではクリーンアップします）
--model MODELcodex exec --model に渡します（例：gpt-5-codex）
--resume UUIDID で特定の codex セッションを再開します。呼び出し元が UUID を把握している場合に便利です
--resume-last-vision直近の codex-vision セッションを強制的に再開します（~/.claude/skills/codex-vision/.last-session-uuid にキャッシュされています）
--freshプロンプトの表現がスマート再開ヒューリスティックに該当する場合でも、必ず新しい codex セッションを開始します
セッションの継続

このラッパーは後続の呼び出しでも codex のコンテキストを維持するため、モックアップの反復や更新されたスクリーンショットの再レビューで、コールドスタートのコストを二度負担せずに済みます。呼び出しが成功するたびに codex セッション UUID が ~/.claude/skills/codex-vision/.last-session-uuid に記録され、次の呼び出しでは簡単なヒューリスティックを使ってこのキャッシュを参照します。

  • 自動再開は review のみに適用されます。review プロンプトに後続作業を示す表現（continue、iterate、follow up、based on the previous、again with、now also、now add、also add、refine、tweak、as before、same image、keep going）が含まれている場合、ラッパーはキャッシュされたセッションを自動再開します（更新されたスクリーンショットの再レビューでもコンテキストが維持されます）。
  • generate／edit は自動再開されません（後続作業を示す表現があっても同様です）。画像セッションを再開すると、ほぼ同じ画像が再出力されるためです（同一画像を再生成するバグ）。--resume <UUID>／--resume-last-vision を指定しない限り、新しいセッションを開始します。
  • それ以外の場合、ラッパーは新しいセッションを開始し、新しい UUID でキャッシュを更新します。

フラグの優先順位は次のとおりです。--fresh（必ず新規）> --resume UUID （指定された UUID を使用）> --resume-last-vision（キャッシュを強制的に使用）> ヒューリスティック。

再開したセッションでは、元のターンの codex サンドボックスとワークスペース設定が再利用されます。そのため、generate／edit は --sandbox を再指定しなくても、初回と同じ OUT_PATH の親ディレクトリに書き込みます。キャッシュファイルがない場合、ヒューリスティックはエラーを出さずに新しいセッションへ移行します。

Claude が従うべき規約
  • tmux セッションには必ず claude-codex- をプレフィックスとして付けてください。 スクリプトで強制されます。これを回避してはいけません。ユーザーは tmux ls | grep claude-codex- で Claude が作成したセッションを識別できます。
  • ログは /tmp/claude-codex-<slug>.log に出力します。 ユーザーが個別に tail -f できるよう、予測可能な場所に保存します。
  • 画像はデフォルトで /tmp/codex-vision-out/ に出力します。
  • codex-vision の画像を .agent/codex/ に書き込まないでください。 このフォルダーは永続的なリポジトリ単位の Codex／tmux セッション用です。
  • --tmux を使うのは、 実行に 30 秒以上かかる見込みがある場合、ユーザーが実行状況の確認や中断を希望する場合、またはユーザーが明示的にセッションを求めた場合に限ります。短時間の画像レビューでは、デフォルトで同期モードを使用します。
  • 複合ワークフロー（入力画像と生成された出力の両方を扱う）の場合は、edit モードを使用します。1 回の Codex 呼び出しで両方を設定できます。

例

# Quick screenshot review
~/.claude/skills/codex-vision/scripts/codex-vision.sh review /tmp/ui.png "What's wrong with this layout?"

# Image generation
~/.claude/skills/codex-vision/scripts/codex-vision.sh generate "isometric diagram of a 4-trajectory GRPO group with advantages" --out /tmp/grpo.png

# Image editing
~/.claude/skills/codex-vision/scripts/codex-vision.sh edit /tmp/raw.png "remove the red overlay; make background transparent" --out /tmp/clean.png

# Long observable review
~/.claude/skills/codex-vision/scripts/codex-vision.sh review /tmp/ui.png "deep walk-through" --tmux ui-review
# user attaches with: tmux attach -t claude-codex-ui-review

このスキルが実行されたときに Claude が行うこと

  1. ユーザーの意図からモードを特定します：レビュー（画像を見る）／生成（画像を作る）／編集（画像を変更する）。
  2. 画像のパスを解決します — 画像はすでにディスク上に存在している必要があります。ユーザーが URL を指定した場合は、まず /tmp/ にダウンロードします。
  3. シェルラッパーを使ってコマンドを組み立てます。Bash を 1 回だけ呼び出します。
  4. 同期実行と --tmux のどちらかを選びます：短いタスクには同期実行、ユーザーが実行を見たい場合やタスクに時間がかかる場合は --tmux を使います。
  5. 呼び出し後、Codex のテキスト応答（レビューモード）、または出力パスと 1 行の要約（生成／編集モード）を返します。
  6. OUT_PATH に生成ファイルが存在する場合は、ユーザーに提示します（例：「画像を /tmp/codex-vision-out/... に保存しました」）。

前提条件

このスキルでは、以下を前提としています：

  • Codex CLI がインストールされていること（macOS では /Applications/Codex.app/Contents/Resources/codex、または OpenAI Codex CLI から PATH 上にある codex）
  • Codex の認証が済んでいること — ユーザーが一度 codex login を実行している（または Codex.app にサインインしている）
  • --tmux を使う場合は tmux がインストールされていること（macOS では brew install tmux）

スクリプトは次の順序で codex バイナリを自動検出します：

  1. $CODEX_VISION_CODEX_BIN（明示的な上書き — 任意の codex バイナリを指定します）
  2. which codex（PATH 上の任意の場所）
  3. /Applications/Codex.app/Contents/Resources/codex（単体の Codex.app）
  4. /Applications/ChatGPT.app/Contents/Resources/codex（ChatGPT.app に同梱された codex — Codex アプリが ChatGPT.app に統合されたもの）
  5. ユーザーごとの ~/Applications/ にある上記 2 つのバンドル
  6. 明確なエラーメッセージを表示して失敗

codex が通常とは異なる場所にある場合は、export CODEX_VISION_CODEX_BIN=/path/to/codex を実行してください。

ユーザーによるスキルのインストール方法

ユーザーから「codex-vision をインストールする方法」について尋ねられた場合や、誰かと共有したい場合は、npx skills からインストールします。

Claude Code 専用 — ~/.claude/skills/codex-vision/ に直接配置します：

npx skills add thenamangoyal/codex-vision -g -a claude-code -y

すべてのエージェントに一括インストール — Claude Code、Cursor、Codex CLI、Gemini CLI。ソースは ~/.agents/skills/codex-vision/ に一度だけ書き込まれ、各エージェントのスキルディレクトリにシンボリックリンクされます：

npx skills add thenamangoyal/codex-vision -g --all

@v0.3.1 を指定すると、特定のバージョンに固定できます。プロジェクト単位でインストールするには -g を省略します。アンインストールするには npx skills remove codex-vision を実行します。

確認：

~/.claude/skills/codex-vision/scripts/codex-vision.sh doctor
~/.claude/skills/codex-vision/scripts/codex-vision.sh selftest

代替の直接インストール（npx skills を使わない場合）：git clone https://github.com/thenamangoyal/codex-vision ~/.claude/skills/codex-vision。

トリガーテスト

トリガー評価（tests/triggering/cases.yaml + scripts/check-triggering.sh） では、このマニフェストの実行条件を、手作業で作成した 50 個のユーザープロンプトに対してベンチマークします — 15 個は実行、20 個はスキップ、15 個は確認を要求する必要があります。ランナーはすべてのケースを 1 回の codex exec 呼び出しにまとめ、判定結果を解析し、誤検知 （skip／clarify が期待されているのにモデルが FIRE と回答）または誤検出漏れ（fire が期待されているのにモデルが SKIP／CLARIFY と回答）が 1 つでもあれば失敗します。v0.3.2 時点で、3 回の試行すべてで 50/50 の安定した結果が得られています。次のコマンドで実行します：

bash ~/.claude/skills/codex-vision/scripts/check-triggering.sh             # one trial
bash ~/.claude/skills/codex-vision/scripts/check-triggering.sh --runs 3    # majority over 3

YAML の description、または When to invoke／When NOT to invoke のセクションを変更した場合は、テストを再実行し、50/50 に戻るまで表現を調整してください。

セッションモードのストレステスト

セッション継続ロジックには、独自のリグレッションテスト tests/session-modes/check-session-modes.sh があります。codex CLI をスタブ化し、 プライベートな CODEX_HOME の下に現実的なロールアウトファイルを作成して、 4 つの主要な動作を検証します：デフォルトで新規セッション、--resume UUID、ヒューリスティックによる再開（プロンプトにフォローアップを示す表現が含まれる）、ヒューリスティックによる新規セッション（プロンプトに含まれない）。 5 つ目のケースでは、--fresh がヒューリスティックより優先されることを確認します。実行ごとに、 tests/session-modes/results-<timestamp>.md に Markdown の要約が書き込まれます。次のコマンドで実行します：

bash ~/.claude/skills/codex-vision/tests/session-modes/check-session-modes.sh

このテストはオフラインで実行されます（ネットワークも実際の codex 呼び出しも使用しません）。ラッパーのセッション継続ブロックを編集した後は、テストを再実行してください。

禁止事項

  • claude-codex- プレフィックスを省略しないでください — これは、Claude が起動したセッションをユーザーが識別するためのものです。
  • --keep が渡されていない限り、ログやセッションを残さないでください。
  • ユーザーに確認せず、ユーザーのリポジトリに画像を書き込まないでください。デフォルトの /tmp/codex-vision-out/ は安全です。
  • 5 秒で終わる簡単なレビューに --tmux を使わないでください — その場合は余計な手間がかかるだけです。

コメント

Markdown 対応