HeiGe Codex Skin Studio: A CDP-Based Theme Switcher for Codex Desktop

What HeiGe Codex Skin Studio replaces, and for whom

Codex Desktop ships with one interface, and there is no supported theming surface for it. HeiGe Codex Skin Studio exists to fill that gap: it applies a background image and a matching colour scheme to the desktop client, and it does so without editing app.asar, the application binary, or the signing resources. The README states this plainly in its usage notes, and the same claim appears next to the Windows instructions, which use scripts\windows\install.bat and apply.bat.

The audience is narrow and specific. You already have Codex Desktop installed. You want the window to look like something other than the default. You are willing to run a shell script or a batch file once, and you are not willing to patch the client itself. The project also targets Tencent's CodeBuddy desktop client, referred to throughout as WorkBuddy, through the same engine on a different port. That second target is the more interesting one, because its limitations are documented more honestly than most theming tools document anything.

Twelve built-in themes ship with it, including a high-detail Miku 488137 preset and lighter Genshin Impact, Wuthering Waves, Naruto, and Love and Deepspace sets, plus Dragon Ball variants and a novelty preset. The built-in presets also flip Codex's own light or dark appearance, so the theme is not only a background layer.

How the CDP injection works and why app.asar stays untouched

The mechanism is loopback Chrome DevTools Protocol. Codex Desktop is an Electron application, and the project connects to its renderer over 127.0.0.1:9341, then injects the theme. WorkBuddy uses 127.0.0.1:9342 so the two do not collide. Because the theme arrives through the debugging channel at runtime rather than through the packaged resources, the application bundle is never rewritten, and restoring the official interface is a matter of stopping the injection.

The repository layout supports that reading. There is a src/ directory, a native/ directory, a scripts/ directory split by platform, and a themes/ directory holding per-theme assets such as themes/dragonball-nimbus/hero.webp. The CLI is exposed as heige-codex-skin in package.json, pointing at src/cli.mjs, with npm scripts for doctor, status, list, and apply. That is a conventional Node toolchain wrapped around a fairly unusual delivery method.

The README is candid that this approach has a shelf life. It notes that if Codex Desktop changes its launch arguments or interface structure in the future, the project may still need to adapt. That is the honest version of the trade-off: nothing is modified on disk, but the injection depends on the client's internal shape, and that shape is not a public contract.

Installing on macOS and applying your first theme

The README's quick start assumes Codex Desktop is already installed. Download the repository, then run the installer by double-clicking or from a terminal:

open "<仓库路径>/scripts/install.command"

After installation the Miku preset is applied by default, and a launcher app is created or upgraded in $HOME/Applications under the name HeiGe 皮肤启动器. That launcher is the recovery surface: after a reboot, a Codex or WorkBuddy update, or a normal launch that drops the skin, you open it and pick the product card. It also offers a one-click repair action, which performs a clean restart of the installed product and restores its most recent skin. The README warns to save your current work before using it.

The launcher deliberately does not duplicate theme selection. Day-to-day switching happens inside the target app through the theme menu at the top. If you prefer the command line, package.json defines the entry point directly:

node src/cli.mjs apply

The repository also exposes npm run doctor and npm run status for diagnostics and current-state checks. The project requires Node.js 22 or newer, which package.json enforces through its engines field. Note that this requirement is stated for WorkBuddy in the README, and the engines field applies it to the package as a whole.

Making a theme from one image, three ways

The README offers three routes, and they differ in how much work you do. The simplest is the theme menu's custom image entry: upload an image, and it is written into the local user theme library as a proper user theme, with automatic colour extraction and automatic light or dark appearance matching. The second route is to double-click customize.command with any PNG, JPG, JPEG, or WebP file, which generates a full skin consisting of a colour scheme and a background image. The third hands the job to an AI: you give output/heige-codex-skin-studio.skill to Codex and ask it to generate an image and turn that image into a skin, with no extra API key required.

There is a wrinkle worth knowing about, and the README does not hide it. New uploads through the menu go into the local user theme library and are registered with the launcher, so they can survive restarts under the persistent skin option, and re-uploading the same name and image overwrites idempotently. The older custom-upload slot is described as a local compatibility slot that the renderer's local storage can keep displaying; it is no longer the authoritative store for new uploads. If you have themes from an earlier version, that distinction is the one to check.

A prompt library lives at docs/theme-prompts.md with eight styles, and the discussion board is where the README invites you to post results. The repository also ships an optional Miku Future animated desktop pet, which does not overwrite Codex's built-in pet.

WorkBuddy support, and the limitation that defines it

The WorkBuddy integration runs on 127.0.0.1:9342 and does not modify app.asar either. Applying it looks like this:

"<仓库路径>/scripts/workbuddy-apply.command" --restart

After that, a theme centre appears at the top of WorkBuddy and built-in themes switch with a click. Restoring uses scripts/workbuddy-restore.command. The README then lists three statements it labels as plain facts, and the first one matters most: WorkBuddy gets a one-shot skin only, with no persistence. The reason given is technical. WorkBuddy's renderer is a local file:// page, so when it calls back to the control service the origin is null, and allowing that would weaken the control service's origin validation. Rather than loosen the check, the project does not open the control channel for WorkBuddy at all. Restarting WorkBuddy therefore loses the skin, and you re-run apply. That is expected behaviour, not a bug.

The other two statements are equally concrete. WorkBuddy needs Node.js 22 or newer on the machine because WorkBuddy itself does not bundle an executable Node. And macOS verification was done on WorkBuddy 5.3.11, while the Windows side is described as structure only, not verified on real hardware. If you are on Windows and expecting WorkBuddy theming to work, that is the sentence to reread.

Windows, MSIX, and the parts that are not verified

Windows 11 support exists and installs through scripts\windows\install.bat, with apply.ps1 as the daily entry point and enable-skin.bat as a compatibility name that restores only the current session. Pause and resume are separate scripts, restore reverts to the native interface, and uninstall.bat deregisters the per-user scheduled task, removes the Start menu entry, and cleans AppData state and the stable install directory. The README notes that uninstall can still run from the source directory even if the stable install directory was deleted by hand, which is a thoughtful detail.

Persistence on Windows works differently from macOS. Turning on the persistent skin option registers a logon scheduled task for the current user, and the README says you must restart Windows or sign out and back in once after enabling it for the first time. After that, the background skin controller starts at logon and restores the theme and the top entry point on the next ordinary Codex launch. The top entry can also be collapsed to a small dot through the hide-this-button option, and there is a persistent random theme toggle that tries to avoid consecutive repeats.

The unverified area is the Microsoft Store and MSIX client. The README says it still needs real-hardware verification. If the store build reports loopback isolation, you can run scripts\windows\enable-loopback.bat once with administrator rights and retry apply. The README is explicit that automatic takeover cannot complete while the port remains unreachable. That is a genuine failure mode, not a footnote: on a store build without the loopback exemption, apply simply will not connect.

Maintenance, licence, and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-13, with release v5.5.17 tagged the same day. Releases have been frequent, with v5.5.16 on 2026-09-04 and v5.5.15 on 2026-08-23 before it. That cadence tells you the project is being worked on now, and it also tells you the surface is still moving. The 5.5.15 notes describe a macOS-only dual-product launcher and a batch of WorkBuddy transparency fixes for permission dialogs, task archiving, and expert summoning. Those are the kinds of fixes that come from real use, and they also imply that earlier versions had visible defects in those dialogs.

Licensing is MIT, per the LICENSE file and the badge in the README. That is permissive and unremarkable, but two things sit next to it. The repository carries ASSET_PROVENANCE.md and NOTICE.md, and package.json defines release:check as node --test plus scripts/check-asset-provenance.mjs --release. Theme assets are the kind of thing that attracts provenance questions, and the project has built a release gate around them. If you plan to redistribute the theme images, read those files yourself. Nothing here is legal advice.

Upgrade cost is mostly re-running the installer or the apply script after a Codex or WorkBuddy update drops the skin. On macOS the launcher handles that; on Windows the scheduled task handles it once enabled. The larger cost is the adaptation risk the README already names: a change to Codex Desktop's launch arguments or interface structure can break injection until the project catches up.

Alternatives, and when not to reach for this

The obvious alternative is to patch the Electron application directly, editing app.asar or the packaged resources so the theme is baked in. That approach survives restarts without a controller process and does not depend on a debugging port, but it modifies the application bundle and its signing resources, and it has to be redone after every client update. HeiGe Codex Skin Studio takes the opposite position: no disk modification, a runtime channel, and a documented dependency on the client's internal structure. Neither is strictly better. If you want a theme that is simply there, with no launcher and no scheduled task, the patching route gives you that at the cost of reversibility.

A second alternative is to leave the client alone and change your desktop environment instead, through window decorations or a compositor. That never touches Codex and cannot break it, but it cannot restyle the sidebar, the input box, or the suggestion cards, which are the parts the project's screenshots actually show.

There are clear cases where this is the wrong tool. If you need WorkBuddy themes to persist across restarts, the origin-null constraint means the project will not do it. If you are on a Microsoft Store or MSIX build without the loopback exemption, apply cannot connect. If you cannot install Node.js 22 or newer, WorkBuddy support is out and the CLI scripts are out. And if a client update breaks the injection, the fallback is the launcher's one-click repair or a re-run of apply, not a fix you can write yourself unless you are willing to read src/.

Editorial conclusion

Adopt it if you run Codex Desktop on macOS, want a cosmetic change you can undo from a menu, and accept that a future Codex UI change may break the injection until the project adapts. Skip it if you need WorkBuddy themes to persist across restarts, if you are on a Microsoft Store or MSIX build, or if you cannot install Node.js 22 or newer. Before committing, run scripts/install.command on macOS and confirm the skin launcher appears in $HOME/Applications, then test the one-click repair once with your work saved so you know how recovery behaves on your machine.

Frequently asked questions

Official sources

1. HeiGeAi/heige-codex-skin-studio on GitHub
2. License: MIT
3. Project website
4. README
5. Releases