Codex-QQ-Skin: a Codex desktop skin generator with a QQ 2007 mode and a local token levelling system

The narrow problem Codex-QQ-Skin solves

The official Codex/ChatGPT desktop app ships one interface. Codex-QQ-Skin exists for people who want that interface to look like something else without forking the app or editing its bundle. The README is explicit about the boundary: the project states it does not modify the official .app, app.asar, code signing, API key or base URL, and that it is not an OpenAI, Tencent or QQ product.

That boundary is the whole point. Reskinning a signed Electron app normally means patching app.asar, which breaks the signature and has to be redone after every update. Codex-QQ-Skin instead listens on 127.0.0.1 and speaks the Chromium DevTools Protocol, injecting styles into the running renderer. The app on disk stays as shipped.

Who it is for is equally narrow. The README lists macOS and Windows support, with a macOS App and a native C# Windows installer. There is no Linux path in the README. The macOS requirements section asks for an official Codex/ChatGPT desktop app that has been launched at least once, and recommends a window width of at least 1180px for the three-column mode. If you are not on one of those two platforms, or you never installed the official app, this project has nothing to attach to.

Three skin modes and how switching actually works

The skin has three modes, switched from the top right: 原生 (native), QQ, and 自定义 (custom). Native restores the official Codex interface and colours. QQ uses a fixed blue-and-silver QQ 2007 frame with a left sidebar, three-column layout, a right-side summary tray and the Codex companion, and the README says it is not affected by user image colours. Custom keeps the native structure and derives its palette, focal point and new-task page composition from an uploaded image.

Switching is described as a full rebuild. The README states that every switch rebuilds the target mode's layout, colours and decorations, so sidebar colours or panel state from the previous skin do not leak through. That is the honest way to do it: incremental patching of an Electron renderer tends to leave orphans, and the release notes for 2.6.1 mention exactly that class of bug, saying native mode no longer leaves the QQ penguin avatar and sidebar profile behind when switching or reinjecting.

The custom mode has a real constraint. It is only selectable after an image has been imported successfully. Images are processed locally, and the README says they are not uploaded. Backgrounds get a uniform blur and light overlay so conversation text stays readable, while portraits and ordinary photos are shown in full on the new-task composition. Only one custom image theme is active at a time from the top-right switch, but the macOS App's skin library manages multiple entries with apply, rename and delete, and the ▾ next to 自定义 in Codex cycles through recent custom skins.

Installing on macOS with the app, and a first real skin

The macOS route the README recommends for ordinary users is the prebuilt app. Download Codex QQ Skin.app.zip from GitHub Releases, unzip it, drag Codex QQ Skin.app into Applications, open it, and click the one-click install and launch button. The app is not signed with an Apple Developer ID and is not notarised, so macOS will likely block the first launch. The README walks through System Settings, Privacy & Security, the security section, then Still Open, followed by a password or Touch ID. It also says not to disable macOS security overall and not to run chmod or xattr for this route.

If you prefer the terminal, the README gives this sequence for a ZIP downloaded from the project page. The xattr call removes the macOS quarantine flag from files that came from GitHub, and the README says sudo is not needed for it.

cd ~/Downloads/Codex-QQ-Skin
xattr -dr com.apple.quarantine .
chmod +x ./*.command scripts/*.sh
./scripts/install-qq-skin-macos.sh

The runtime engine installs to ~/.codex/codex-qq-skin-studio, and themes and runtime state live in ~/Library/Application Support/CodexQQSkin. To check that injection actually happened rather than assuming it, the README lists a verification script that inspects signature, runtime and injection result and takes a screenshot.

./scripts/doctor-macos.sh --require-live

The daily entry points are shell scripts in the repository. Start launches the retro theme, pause stops it, and restore returns the app to the official look and restarts Codex.

./scripts/start-qq-skin-macos.sh
./scripts/pause-qq-skin-macos.sh
./scripts/restore-qq-skin-macos.sh --restore-base-theme --restart-codex

For a custom background from the command line, the README shows a load-image script taking an absolute file path plus appearance, safe-area and task-mode options. Re-running the start script applies it, and the README notes the QQ title bar, three-column layout and companion card are not replaced by this path.

./scripts/load-image-theme-macos.sh --file /absolute/path/your-image.png \
  --appearance light \
  --safe-area center \
  --task-mode off

The token growth centre reads your local session logs

The QQ mode's top right shows a growth centre instead of the native output panel. It reports today's Codex tokens, the last seven days, all-time cumulative, a seven-day trend, active days and consecutive active days. Growth points come from active days and daily total token bands, and the level is drawn with QQ's star, moon, sun and crown icons.

The data path is local. The README states the statistics read ~/.codex/sessions and archived_sessions directly, use an incremental cache, need no extra account, do not read the API key, and do not upload prompts or token data. It also says fork and sub-agent inherited history and duplicate token events are de-duplicated.

Two details are worth taking seriously. First, there is a 净用量 (net usage) toggle on the level row that excludes cached input from the figures; the default is total usage, which includes cache. Second, the README admits the current logs have no stable account identifier, so the panel labels itself as local-machine statistics and a local Codex level, not an OpenAI bill and not a cloud account level. That is a fair disclosure, and it also means the number you see is only meaningful for the machine you are sitting at. If you work across several machines, there is no merged view.

Clicking 资料 in that corner restores the native output and sources panel, and 成长统计 switches back. The README describes this as lossless, so the growth centre is an overlay on the native panel rather than a replacement for it.

Where Codex-QQ-Skin breaks or is the wrong tool

The most obvious failure mode is version drift. Codex-QQ-Skin injects into whatever DOM the current Codex build renders. The 2.6.1 release notes describe recognising a new home-banners structure on the home page and switching layout by DOM inspection to fix a blank new-task panel under QQ and custom skins, while old Codex versions without banners keep the original injection path. That is a maintenance treadmill: every upstream layout change is a potential blank panel, and the project has to react. The README does not document a rollback for a skin that renders badly on a new Codex build, though the restore script returns the app to the official appearance.

The second constraint is the injection channel itself. The Windows installer works by listening on 127.0.0.1 over the Chromium DevTools Protocol. Anything that opens a debugging port on a desktop app is worth a conscious decision. On a shared or managed machine, that may be against local policy regardless of what the tool does with the connection. The README does not describe authentication on that port.

The third is the installer trust story. The Windows EXE is not commercially code-signed, so SmartScreen may warn on first run; the README tells you to download only from the repository's official releases and check the SHA-256. The macOS app is likewise unsigned and un-notarised. If your environment requires signed and notarised software, this project does not meet that bar today.

Finally, the README does not list Linux support anywhere, and the three-column QQ layout needs roughly 1180px of window width. On a small laptop screen, or on a platform the project does not cover, it is simply the wrong tool.

How it differs from patching app.asar or forking the app

The common alternative for reskinning an Electron desktop app is to unpack and edit app.asar, or to run a patched fork of the application. That approach gives you durable changes that survive without a helper process, and it lets you change behaviour, not just appearance. The cost is that the bundle's code signature no longer matches, macOS and Windows may refuse to launch it, and every upstream update means re-applying the patch against a new archive. Codex-QQ-Skin's README states plainly that it does not modify the official .app, app.asar, code signing, API key or base URL, which is the direct trade: nothing on disk changes, but the skin only exists while the injector is running and attached.

A second alternative is the official app's own theming and settings. The README's native mode exists precisely to return to that, and the QQ mode's 资料 button hands the output and sources panel back to the real Codex UI. If all you want is a different colour scheme inside what the app already allows, you do not need this project.

A third comparison is to other skin generators for the same app. The distinguishing design choice here is the deep skin helper, which the README describes as generating two internal reference images plus background and transparent layered assets from a single theme keyword, then creating a .codexskin file, installing it, applying it and verifying the real Codex interface. That is a heavier pipeline than picking a background image, and it depends on a Skill being installed into Codex first.

Maintenance cost, licence and what the repository does not pin down

The repository is MIT licensed, with a NOTICE.md alongside the LICENSE file. MIT is permissive: you can use, modify and redistribute the code provided the copyright notice and permission notice are preserved. That is a description of the licence text, not legal advice, and the bundled assets deserve their own look. The README mentions that the completion sound is a QQ system message sound labelled CC0 on a third-party page, while other sounds are synthesised locally with Web Audio, and that the built-in skins ship inside the installer. Asset provenance for the QQ visual elements is not spelled out in the README, so check NOTICE.md before redistributing.

Upgrade cost is real and recurring. The macOS app auto-updates only to strictly newer versions, never downgrades, and never re-updates the same version. The Windows installer reports the deep skin helper as installed, updatable, or already installed. The project tracks Codex releases closely, as the 2.6.1 notes about Codex 26.721 compatibility show, and package.json requires Node.js 20 or newer for the build scripts, though the README says end users do not need to install Node.js because the runtime uses the Node.js signed inside the official Codex app.

The last push was on 2026-08-11, and the most recent release listed is v3.3.0 (CodexGF-Live 3.3.0) on the same date. Note the version mismatch: package.json reads 2.6.3 while the releases list carries 3.3.0 tags. The README does not explain how those two version lines relate, and that is worth resolving before you build anything from source. The README also does not document rollback of a bad skin, only restore to the official appearance.

Editorial conclusion

Adopt Codex-QQ-Skin if you run the official Codex or ChatGPT desktop app on macOS or Windows, you want a fixed retro QQ 2007 layout or image-derived custom themes, and you accept that the tool attaches to the app over a local DevTools port rather than patching files. Skip it on Linux, on any machine where you cannot allow a localhost debugging port, and on window widths below 1180px, where the three-column QQ layout will not fit. Before installing, confirm the release you download matches the SHA-256 published with that release, check that the installer reports the deep skin helper as installed, and run ./scripts/doctor-macos.sh --require-live to see whether injection actually took effect on your Codex build.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zhulin025/Codex-QQ-Skin on GitHub