Codex Styler

An open-source Codex theme editor and Codex skin creator for OpenAI Codex Desktop.
Safe, reversible, local-first, and deliberately unofficial.

简体中文 · Download Alpha · Website · Documentation

Important

Codex Styler is an Alpha preview. The macOS download is ad-hoc signed but not signed with an Apple Developer ID or notarized; it is not a stable release. v1 Stable remains gated on complete real-device testing, macOS notarization, and Windows code signing.

_{Gilded Grandeur + Reset God — a live Codex Desktop workspace styled by Codex Styler.}

Themes that reshape Codex

Codex Styler treats a Codex theme as a coordinated visual system—not a background swap. Semantic surfaces, navigation, icons, borders, depth, motion, the composer, and an optional companion change together while the familiar Codex structure remains intact.

_{Merry Big Top + Token Thief — the same Codex skeleton, rebuilt with a different color, material, motion, and companion direction.}

Meet the companions

Companions are draggable, pointer-aware, and independent from themes. A built-in theme can recommend a pairing, but you can combine any companion with any visual system—or use no companion at all.

Moss Curious chameleon	Reset God Gilded calm	Token Thief Circus mischief
Pico Expressive parrot	Puddle Grounded frog	Mochi Warm orange cat

Why Codex Styler

OpenAI Codex Desktop already includes useful appearance controls and Pets. Codex Styler focuses on the layer they do not cover: image-led environments, restrained material styling, and replaceable 2D entities that can react to the pointer.

• Reversible runtime: launches Codex with a temporary loopback CDP session; never edits app.asar, application resources, or signatures.
• Image-adaptive creator: import a local PNG, JPEG, or WebP and Styler derives luminance, dominant color, accent, and contrast before fitting the image to one of four curated visual systems. You can then refine layout, icon treatment, details, surfaces, radius, motion, and companion placement without authoring CSS.
• Open scene model: themes declare layers[], entities[], a renderer, and behaviors instead of reaching into Codex DOM internals.
• Data-only packages: local raster assets and JSON; no scripts, arbitrary CSS, SVG, video, remote URLs, or executable fonts.
• Local-first: no account, telemetry, cloud sync, or online store; optional update checks only contact GitHub Releases.
• Bilingual from v1: English and Simplified Chinese in the desktop app, repository, and documentation site.

One manager, light or dark

The Codex Styler manager follows the system or uses an explicit light or dark appearance. Its interface appearance is independent from the theme applied to Codex.

Light

Dark

Built-in themes

Theme	Direction	Interaction
Native Refined	Low-distraction calibration of the native workspace	Moss + restrained motion
Gilded Grandeur	Obsidian architecture and controlled gilded detail	Reset God + golden parallax
Merry Big Top	Playful circus color and rounded theatrical surfaces	Token Thief + buoyant motion
Nocturne Studio	Ink-dark architecture, smoked glass, and amber light	Moss + cinematic parallax
Quiet Garden	Soft natural depth and readable translucent surfaces	Moss + natural parallax

Companions are selected independently from themes. Native Refined, Nocturne Studio, and Quiet Garden recommend Moss; Gilded Grandeur recommends Reset God; Merry Big Top recommends Token Thief. Pico, Puddle, and Mochi remain available from the companion library. Choosing another companion or No companion becomes an explicit preference and is never overwritten by later theme changes. Each video-derived companion uses a calibrated, non-linear direction map instead of assuming constant source-video speed; natural pose changes remain intact, while every frame shares one lossless-alpha crop and ground line. Companions can be dragged freely or snapped to a semantic Codex surface, and a resize observer keeps them attached when the composer changes height.

Every shipped image and sprite is original project artwork. The reference repositories are studied for ideas only; their assets and source are not redistributed.

Download the macOS Alpha

Download Codex Styler 0.1.0-alpha.5 for macOS Apple Silicon (.dmg)

Requires macOS 13 or later and an Apple Silicon Mac. Open the DMG, drag Codex Styler to Applications, then Control-click the app and choose Open on first launch. Do not disable Gatekeeper globally.

The pre-release page includes SHA-256 checksums, an SPDX SBOM, build attestations, tested scope, and known limitations. Windows and Intel macOS installers are not included in this Alpha.

Run from source

Requirements

• Node.js 22 or newer
• pnpm 11 or newer
• Rust stable
• OpenAI Codex Desktop for real runtime testing

pnpm install
pnpm check
pnpm tauri dev

Run only the browser-based interface:

pnpm dev

Run the bilingual documentation site:

pnpm dev:site

Safety model

Codex Styler reserves a random port on 127.0.0.1, starts the installed Codex executable with that temporary debugging port, validates the returned page target, and injects one idempotent scene root plus one style node. Restore removes both.

The default Enhanced mode first applies the complete semantic treatment—including navigation, content surfaces, composer, dialogs, and the thread summary panel—then checks live anchors and computed styles. A different Codex version is informational, not a failure. Styler falls back only when the runtime health check detects an actual structural or rendering problem. Conservative mode always limits styling to the isolated background and scene layer. When Codex is already open, Styler asks for confirmation before sending a normal quit request and relaunching it; it never force-quits the process.

See the security model, theme package specification, and security policy.

Theme format

A .codex-styler-theme file is a validated ZIP containing:

theme.json
LICENSES.json
assets/*.png | *.jpg | *.webp
previews/*.png | *.jpg | *.webp

The public format identifier is codex-styler-theme-v1. The JSON Schema and TypeScript interfaces live in packages/theme-core.

Validate a manifest or package:

pnpm theme:validate path/to/theme.json
pnpm theme:validate path/to/theme.codex-styler-theme

Project structure

apps/desktop          React editor + Tauri desktop shell
apps/site             Astro bilingual website and documentation
packages/theme-core   Theme schema, validation, archives, built-in themes
docs                  Architecture, safety, assets, and decisions

The runtime is intentionally split into four boundaries:

1. Desktop manager
2. Theme engine
3. Versioned Codex adapter
4. Injected scene runtime

Theme packages never contain Codex selectors. Compatibility-sensitive behavior stays inside the adapter.

Contributing

Read CONTRIBUTING.md before opening a pull request. Original themes, accessibility improvements, adapter fixtures, documentation, and real-device compatibility reports are especially useful.

Please report security issues through GitHub private vulnerability reporting, not a public issue.

Status and roadmap

The current repository implements the Foundation and macOS prototype layers. The next public gates are:

• macOS Alpha with documented unsigned-preview warnings
• Windows 11 x64 Beta with real-device validation
• signed and notarized v1 Stable on both platforms

See ROADMAP.md and COMPATIBILITY.md.

Licensing and trademark notice

Code is licensed under Apache-2.0. Original bundled artwork is licensed under CC BY 4.0.

Codex Styler is not affiliated with, endorsed by, or sponsored by OpenAI. OpenAI and Codex are trademarks of OpenAI, L.L.C.; their names are used only to describe compatibility.