codex-theme-switcher

アクティブな Codex テーマを切り替える

管理されているローカルライブラリ ~/.codexthemes/themes/<theme-id>/ のテーマを実行中の Codex デスクトップアプリに適用したり、インストール済みテーマを切り替えたり、標準の外観に戻したり、実際に適用されているテーマを確認したりできます。このスキルは単独で動作し、TypeScript スクリプトが可逆的なインジェクションランタイムを管理します。テーマの作成や編集（codex-theme-creator）、ギャラリーからのインストール（codex-theme-installer）、公開（codex-theme-submitter）は行いません。必要なローカルツールは Node.js 20 以降、npx、公式の Codex デスクトップアプリのみです。

すべてのコマンドは、インストール済みのスキルディレクトリから実行してください。ランタイムは Codex のループバック専用デバッグエンドポイントを介して、管理対象の <style> 要素のみを挿入します。署名済みアプリバンドルは変更せず、1 つのウィンドウだけでなく、開いている すべての Codex ページにテーマを適用します。

ステップ 1：テーマを選ぶ

npx tsx scripts/switch-theme.ts list

インストール済みのすべてのテーマ（ID、名前、レイアウトモード）と、現在アクティブなテーマを一覧表示します。テーマは、codex-theme-creator でローカルに作成するか、codexthemes.ai からダウンロードして codex-theme-installer でインストールすると、ライブラリに追加されます。ユーザーが希望するテーマが一覧にない場合は、パスを推測せず、代わりにそれらのスキルに引き継いでください。

ステップ 2：適用または切り替え

npx tsx scripts/switch-theme.ts apply <theme-id>

• Codex がすでにデバッグエンドポイントを公開している場合（以前にテーマを適用して起動した後は公開されています）、開いているすべてのページでテーマがその場でホットスワップされます。再起動は不要で、{"status": "active", "pagesThemed": n} が出力されます。
• エンドポイントがない場合（このアプリセッションで初めて適用する場合、または Codex を完全に終了した場合）は、Codex の再起動についてユーザーの明示的な許可を得てから、--launch を指定して再実行してください。

npx tsx scripts/switch-theme.ts apply <theme-id> --launch

--launch は {"status": "scheduled"} を出力し、終了 → 再起動 → インジェクションの処理を、再起動後も動作する分離されたヘルパーに引き継ぎます（Codex 内でホストされているエージェントは Codex とともに終了するため、ツール呼び出しが中断されることがあります）。独自の再起動機構を作成しないでください。シェルラッパー、launchd やスケジュールされたタスク、スクリプトのコピーは使用しないでください。ヘルパーはすでに再起動後も動作します。

ランチャーは macOS と Windows に対応しています。Windows では Codex／ChatGPT の実行ファイルを検出し（実行中プロセスのパス、%LOCALAPPDATA%\Programs\...、または WindowsApps の実行エイリアス）、検出できない場合は --app に完全な .exe パスを指定してください。taskkill で正常に終了させ（/F は使用しません）、デバッグフラグを付けて再起動します。再起動後もエンドポイントが現れない場合、そのインストール済みビルド（Microsoft Store パッケージなど）はデバッグフラグを無視しています。その制限を明確に伝えてください。WindowsApps またはインストールディレクトリ内のファイルは決して変更しないでください。

組み込みの可読性チェック

適用のたびに、インジェクション後に実際に描画されたピクセルを測定し、表示されているテキストのコントラストをスクリーンショットから判定します。テーマによってテキストが読めなくなる場合、適用は自動的に取り消され、以前アクティブだったテーマ（または標準の外観）に戻ります。その際、測定結果を含む {"status": "reverted", "failures": [...]} が報告されます。テーマが提供された状態では正常に動作しないことをユーザーに伝え、codex-theme-creator での修正を提案してください。ユーザーが読めないテーマをそれでも使い続けたいと明示した場合に限り、--force を指定してください。

ステップ 3：確認 — scheduled は成功ではありません

npx tsx scripts/switch-theme.ts status

status は実行中のすべての Codex ページを確認し、active（すべてのページにテーマが適用され、テーマ ID が 1 つ）、partial（ページ間で一致していません。一致させるには再適用してください）、または inactive と、ページごとの根拠を報告します。status で期待するテーマ ID を含む active が表示されてから、ユーザーに成功を報告してください。--launch の後も inactive のままの場合は、~/.codexthemes/state/launch.log を読んでヘルパーの結果を確認してください。

ホットスワップが成功した後も古いテーマが再び適用される場合（以前のタスクの古いセッションがまだテーマを再注入しており、そのセッションの外からは登録を削除できないため）、ユーザーに再起動の許可を求め、安全に再起動してください。ユーザーに手動でアプリを終了するよう求めてはいけません。

npx tsx scripts/switch-theme.ts apply <theme-id> --launch --relaunch

--relaunch は、すでにエンドポイントが稼働中でも Codex を再起動します。これにより古いセッションをすべて終了してから、指定されたテーマを注入します。通常と同じく、scheduled → status の順で確認します。

ステップ 4：必ずユーザーに元に戻す方法を伝える

テーマの適用に成功したことを報告する際は、active の出力にある背景の適用範囲も必ず伝えてください。これにより、アートワークがホームページにしか表示されないことをユーザーが意外に思わずに済みます。backgroundScopeNote の内容を平易な言葉で伝えてください。例：「背景のアートワークはホームページにのみ表示され、色はすべてのページに適用されます。会話ページにも背景を表示するには、codex-theme-creator に backgroundScope: workspace を指定して再構築するよう依頼してください。」その後、元に戻す方法を案内してください。例：「以前のテーマに戻すには rollback、Codex 本来の外観に戻すには restore と返信してください。Codex を完全に終了してもテーマは解除されます。」結果が気に入らないユーザーが、元に戻す方法や適用範囲を変更する方法を尋ねる必要があってはいけません。

適用のたびに、適用前のテーマが記録されます。ユーザーが rollback と返信した場合（または新しいテーマが壊れている、見た目が悪い、希望と違うと言った場合）：

npx tsx scripts/switch-theme.ts rollback

以前に有効だったテーマを再適用します。該当するテーマがない場合は、Codex 本来の外観に戻します。通常と同じ適用パイプラインを実行するため、可読性チェックと status による確認も行われます。（可読性チェックに失敗したテーマは、適用時に自動で元に戻るため、手動でのロールバックは必要ありません。）

ユーザーが Codex 本来の外観に戻すよう求めた場合（または restore と返信した場合）：

npx tsx scripts/switch-theme.ts restore

すべてのページから注入されたスタイルとページマーカーを削除し、ランタイム状態をクリアします。再起動は不要です。アプリケーションを完全に終了してもテーマは解除されます。ユーザーがテーマを再適用したい場合は、--launch を使ってください。復元後もテーマが再び適用される場合は、古いセッションが再注入しています。ユーザーの許可を得て、ステップ 2 の --launch --relaunch の手順を使うか、Codex を完全に終了して再度開くよう案内してください。

境界

• 再起動の前には必ず許可を求めてください。ホットスワップには、テーマの切り替えを求めるユーザーの依頼以外の許可は不要です。
• 再起動が関わる場合、apply の出力だけを根拠にテーマが有効だと主張してはいけません。status で確認してください。
• app.asar、署名済みアプリケーションバンドル、ユーザーのタスク、認証データを変更してはいけません。
• ここでテーマのソースを編集してはいけません。デザインの変更は codex-theme-creator に依頼してください。