codex-theme-switcher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Switch the active Codex theme

切换Codex激活主题

Apply a theme from the managed local library

~/.codexthemes/themes/<theme-id>/

to the running Codex desktop app, switch between installed themes, restore the native look, and verify what is actually active. This skill is standalone: its TypeScript scripts own the reversible injection runtime. It does not create or edit themes (codex-theme-creator), install them from the gallery (codex-theme-installer), or publish them (codex-theme-submitter). The only required local tools are Node.js 20+,

npx

, and the official Codex desktop app.

Run all commands from the installed skill directory. The runtime injects only an owned

<style>

element over Codex's loopback-only debugging endpoint; it never modifies the signed app bundle, and it themes every open Codex page, not just one window.

从托管的本地库

~/.codexthemes/themes/<theme-id>/

中为运行中的Codex桌面应用应用主题、在已安装主题间切换、恢复原生外观，并验证当前实际激活的主题。此Skill为独立工具：其TypeScript脚本拥有可逆注入运行时。它不创建或编辑主题（该功能由codex-theme-creator负责）、不从主题库安装主题（该功能由codex-theme-installer负责），也不发布主题（该功能由codex-theme-submitter负责）。仅需本地安装Node.js 20+、

npx

以及官方Codex桌面应用。

所有命令均需在已安装的Skill目录下运行。运行时仅通过Codex的仅环回调试端点注入自有

<style>

元素；它绝不会修改已签名的应用包，并且会为所有打开的Codex页面设置主题，而非仅单个窗口。

Step 1: pick the theme

步骤1：选择主题

bash

npx tsx scripts/switch-theme.ts list

Lists every installed theme (id, name, layout mode) and which one is currently active. Themes arrive in the library from codex-theme-creator (created locally) or codex-theme-installer (downloaded from codexthemes.ai). If the theme the user wants is not listed, hand off to those skills instead of guessing paths.

bash

npx tsx scripts/switch-theme.ts list

列出所有已安装的主题（ID、名称、布局模式）以及当前激活的主题。主题可通过codex-theme-creator（本地创建）或codex-theme-installer（从codexthemes.ai下载）添加至库中。如果用户需要的主题未列出，请引导至对应Skill处理，而非自行猜测路径。

Step 2: apply or switch

步骤2：应用或切换主题

bash

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

If Codex is already exposing its debugging endpoint (it is after any previous themed launch), this hot-swaps the theme in place on every open page — no restart, output
```
{"status": "active", "pagesThemed": n}
```
.
If there is no endpoint (first apply of this app session, or Codex was fully quit), ask the user for explicit permission to restart Codex, then rerun with
```
--launch
```
:

bash

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

--launch

prints

{"status": "scheduled"}

and hands the quit → relaunch → inject sequence to a detached helper that survives the restart (an agent hosted inside Codex dies with it; expect the tool call to be interrupted). Never build your own restart mechanism — no shell wrappers, launchd or scheduled tasks, or script copies; the helper already survives the restart.

The launcher supports macOS and Windows. On Windows it finds the Codex/ChatGPT executable (running process path,

%LOCALAPPDATA%\Programs\...

, or the WindowsApps execution alias — pass

--app

with the full

.exe

path if detection fails), closes it gracefully with

taskkill

(never

/F

), and relaunches it with the debugging flags. If the endpoint never appears after the relaunch, that installed build (for example a Microsoft Store package) drops the debugging flags — report that limitation plainly; never modify files under

WindowsApps

or the installation directory.

bash

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

如果Codex已暴露其调试端点（在之前任何一次主题化启动后都会开启），此命令将在所有打开的页面上热切换主题——无需重启，输出
```
{"status": "active", "pagesThemed": n}
```
。
如果未检测到端点（为本应用会话首次应用主题，或Codex已完全退出），请先征得用户明确许可后重启Codex，再添加
```
--launch
```
参数重新运行：

bash

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

--launch

参数会输出

{"status": "scheduled"}

，并将退出→重启→注入的流程交给一个独立的辅助程序，该程序可在重启后继续运行（Codex内部的Agent会随应用关闭而终止，因此工具调用会被中断）。请勿自行构建重启机制——不要使用shell包装器、launchd或计划任务，也不要复制脚本；该辅助程序已能在重启后存活。

启动器支持macOS和Windows系统。在Windows上，它会查找Codex/ChatGPT可执行文件（运行进程路径、

%LOCALAPPDATA%\Programs\...

或WindowsApps执行别名——如果检测失败，可通过

--app

参数传入完整的

.exe

路径），使用

taskkill

优雅关闭应用（绝不要使用

/F

参数），并携带调试标志重新启动。如果重启后仍未出现端点，说明该已安装版本（例如Microsoft Store包）会丢弃调试标志——请直接告知用户此限制；绝不要修改WindowsApps或安装目录下的文件。

Built-in readability gate

内置可读性检测机制

Every apply measures the real rendered pixels after injection (screenshot-based contrast of visible text). If the theme leaves text unreadable, the apply automatically reverts to the previously active theme (or the native look) and reports

{"status": "reverted", "failures": [...]}

with the measured evidence. Tell the user the theme is broken as shipped and offer to fix it with codex-theme-creator; pass

--force

only when the user explicitly says they want to keep the unreadable theme anyway.

每次应用主题后，都会通过截图测量注入后实际渲染像素的可见文本对比度。如果主题导致文本无法阅读，应用操作会自动恢复到之前激活的主题（或原生外观），并输出

{"status": "reverted", "failures": [...]}

及测量依据。请告知用户该主题存在问题，并提供codex-theme-creator工具以修复；仅当用户明确表示希望保留该不可读主题时，才使用

--force

参数。

Step 3: verify —

scheduled

is not success

步骤3：验证——“scheduled”不等于成功

bash

npx tsx scripts/switch-theme.ts status

status

probes every live Codex page and reports

active

(all pages themed, one theme id),

partial

(pages disagree — reapply to converge them), or

inactive

, plus the per-page evidence. Only report success to the user after

status

shows

active

with the expected theme id. If it stays

inactive

after a

--launch

, read

~/.codexthemes/state/launch.log

for the helper's result.

If an old theme keeps coming back after a successful hot swap (a stale session from an earlier task is still re-injecting it, and its registrations cannot be removed from outside that session), get the user's restart permission and force a clean relaunch — never ask the user to quit the app by hand:

bash

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

--relaunch

restarts Codex even though an endpoint is already live, which evicts every stale session, then injects the requested theme. It follows the same

scheduled

→

status

verification flow.

bash

npx tsx scripts/switch-theme.ts status

status

命令会探测所有运行中的Codex页面，返回

active

（所有页面均已应用同一主题ID）、

partial

（页面主题不一致——需重新应用以统一）或

inactive

状态，以及各页面的检测依据。仅当

status

显示为

active

且主题ID符合预期时，才可告知用户操作成功。如果使用

--launch

后状态仍为

inactive

，请查看

~/.codexthemes/state/launch.log

获取辅助程序的运行结果。

如果旧主题在成功热切换后反复出现（早期任务的陈旧会话仍在重新注入该主题，且无法从外部移除其注册信息），请征得用户许可后强制干净重启——绝不要让用户手动退出应用：

bash

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

--relaunch

参数会在端点已激活的情况下仍重启Codex，从而清除所有陈旧会话，然后注入请求的主题。它遵循相同的

scheduled

→

status

验证流程。

Step 4: always hand the user the escape hatch

步骤4：始终为用户提供退出方案

Every successful apply report must also state the background scope from the

active

output, so the user is never surprised that artwork is home-only. Relay

backgroundScopeNote

in plain language, for example: "Background artwork shows on the home page only; the colors apply on every page. To show it on conversation pages too, ask codex-theme-creator to rebuild with backgroundScope: workspace." Then end with the undo hints, for example: "Reply

rollback

to return to the theme you had before, or

restore

for the native Codex look — fully quitting Codex also removes the theme." A user who dislikes the result must never have to ask how to undo it or how to change the scope.

Every apply records the previously active theme. When the user replies

rollback

(or says the new theme is broken, ugly, or not what they wanted):

bash

npx tsx scripts/switch-theme.ts rollback

This re-applies the previously active theme, or restores the native look when there is none. It runs through the same apply pipeline, so the readability gate and

status

verification still apply. (A theme that fails the readability gate never needs a manual rollback — the apply auto-reverts on its own.)

When the user asks for the native look instead (or replies

restore

bash

npx tsx scripts/switch-theme.ts restore

Removes the injected style and page markers from every page and clears the runtime state — no restart needed. A full application quit also drops the theme; reapply with

--launch

when the user wants it back. If the theme keeps reappearing after restore, a stale session is re-injecting it — use the

--launch --relaunch

flow from Step 2 with the user's permission, or have them fully quit and reopen Codex.

每次成功应用主题后，必须同时告知用户

active

输出中的背景范围信息，避免用户对主题仅在主页显示感到意外。请用通俗易懂的语言传达

backgroundScopeNote

，例如：“背景图仅在主页显示；颜色会应用于所有页面。若要在对话页面也显示背景图，请使用codex-theme-creator重新构建并设置backgroundScope: workspace。” 然后提供撤销提示，例如：“回复

rollback

可恢复到之前的主题，或回复

restore

恢复Codex原生外观——完全退出Codex也会移除当前主题。” 用户若不满意结果，绝不需要询问如何撤销或更改范围。

每次应用主题都会记录之前激活的主题。当用户回复

rollback

（或表示新主题存在问题、难看或不符合预期）时：

bash

npx tsx scripts/switch-theme.ts rollback

此命令会重新应用之前激活的主题；如果没有之前的主题，则恢复原生外观。它会遵循相同的应用流程，因此可读性检测和

status

验证仍然适用。（未通过可读性检测的主题无需手动回滚——应用操作会自动恢复。）

当用户请求恢复原生外观（或回复

restore

）时：

bash

npx tsx scripts/switch-theme.ts restore

移除所有页面中注入的样式和页面标记，并清除运行时状态——无需重启。完全退出应用也会移除主题；用户如需重新应用，可使用

--launch

参数。如果恢复后主题仍反复出现，说明存在陈旧会话在重新注入主题——请在征得用户许可后使用步骤2中的

--launch --relaunch

流程，或让用户完全退出并重新打开Codex。

Boundaries

边界限制

Ask before any restart; a hot swap needs no permission beyond the user's request to switch.
Never claim a theme is active based on
```
apply
```
output alone when a restart was involved — verify with
```
status
```
.
Never modify
```
app.asar
```
, the signed application bundle, user tasks, or authentication data.
Do not edit theme sources here; route design changes to codex-theme-creator.

任何重启操作前均需征得用户同意；热切换仅需用户提出切换请求即可，无需额外许可。
当涉及重启时，绝不要仅根据
```
apply
```
的输出就声称主题已激活——必须通过
```
status
```
验证。
绝不要修改
```
app.asar
```
、已签名的应用包、用户任务或认证数据。
请勿在此编辑主题源文件；如需修改设计，请引导至codex-theme-creator。