How Codex Skin works

Codex Skin turns one published six-digit theme ID into a verified appearance in the current Codex window. The work is split across the website, public Plugin, signed local Helper, data-only theme package, and an adapter for the official Codex application. No layer can grant access on its own, execute theme code, or declare success from an intermediate state.

This page explains the public system boundaries. It does not publish private selectors, signing keys, Production storage paths, customer data, or administrative configuration.

The system in one request

User in a Codex task
  -> Skill + fixed wrapper
  -> website/API authorization and theme delivery
  -> verified Bootstrap/Helper
  -> signed data-only theme package
  -> official Codex over short-lived loopback control
  -> visible verification
     -> commit success, or roll back

The user starts with a real ID from the gallery. The Skill keeps that ID as a separate argument. The website checks the device and, for a Pro theme, the current access period. The Helper accepts the package only after its release and contents pass verification. It then operates one verified official Codex instance, checks the final visible result, records success only if that result matches the request, and exits.

Browser authorization and Pricing are conditional parts of the same transaction. A callback page, local file, cached package, or editable client state cannot grant Pro access. Payment and access come from verified server-side facts.

Components and ownership

Component	Owns	Does not own
Website and API	Catalog, web session, device approval, access decision, short-lived delivery	Local rendering or arbitrary Helper commands
Plugin, Skills, wrapper	Supported intent, six-digit ID, user warning and confirmation, structured result	Open-ended shell execution or server entitlement
Bootstrap and Helper	Verified local binary path, authorization client, package checks, bounded transaction, Restore	Background auto-reapply or theme-supplied code
Theme package	Manifest, allowlisted design data, declared local images	CSS, JavaScript, selectors, shell commands, executables
Adapter	Official identity, loopback target, capability probes, fixed renderer mapping	Unknown processes, browsers, or unverified surfaces

Website and API

The website publishes the theme catalog and public previews. For protected delivery, it owns the browser session, device approval flow, server-side access check, and short-lived theme response. A Free or Pro package is delivered only to an authorized Plugin device.

For Pro, the server uses verified payment and access records. A signed payment-provider event creates or changes an access period; the browser success page does not. The API can decide whether the current request may download a package, but it cannot send arbitrary CSS, selectors, or local commands to the Helper.

Plugin, Skills, and wrapper

The public Plugin turns natural requests into a fixed set of operations: version, apply or switch by six-digit ID, local status, and offline Restore. The Skill provides the 20–60 second window warning, explains browser approval, asks for explicit restart consent when required, and reports the stable result.

The wrapper invokes a fixed external Helper with fixed arguments. User text, website content, and theme data are never interpolated into a general shell command. A custom API origin, package path, download URL, selector, CSS, JavaScript, or shell fragment is outside the supported interface.

Bootstrap and Helper

The Plugin pins the release-tagged Bootstrap launcher and its platform SHA-256. The launcher retrieves only the expected files from the fixed public GitHub Releases path, then verifies the signed descriptor, platform, size, digest, and Helper self-tests before it activates a candidate.

The Helper is self-contained. Users do not install Node or Go. It handles device authorization, verified theme download, transaction state, native appearance backup, apply, visible verification, rollback, local status, and Restore. State and the recovery engine live outside the replaceable Plugin cache.

Each apply, switch, or Restore is one bounded on-demand Helper operation. It is not a daemon, tray app, login item, or background controller.

Theme package

A theme package contains a versioned manifest and declared local PNG, JPEG, or WebP assets. Its signed descriptor binds the public theme ID, theme version, package or manifest digest, size, schema and verification key information. The engine also validates paths, MIME types, hashes, declared files, and data fields.

The package cannot supply its own executable rendering logic. CSS, JavaScript, Shell, PowerShell, selectors, remote execution URLs, path traversal, symlinks, and undeclared files are rejected.

Adapter and official Codex

Before a dangerous action, the adapter verifies the official Codex application, process, user profile, renderer markers, and loopback CDP endpoint. It does not attach to an arbitrary browser or unknown process. If identity or required capabilities cannot be confirmed, the operation fails closed.

The adapter maps Helper-owned templates and allowlisted design data to supported Codex regions. Chat-specific artwork and colors are scoped to verified Home, conversation, and composer surfaces. Native utility pages keep the matching official light or dark palette.

Device authorization and credentials

Website login and local Plugin authorization are related, but they are not the same credential boundary. The browser page shows the computer and platform being approved. Once the user approves it, the original Plugin transaction continues.

The Plugin's Access Token remains in memory. The rotating Refresh Token is stored in macOS Keychain or Windows Credential Manager. The public Helper does not put credential contents in a normal state file, command arguments, environment variables, or logs.

Local status may report deviceLinked: true. That means a local device reference exists. It does not prove that the current website session is signed in, the server still accepts that device, or Pro access is active. Those checks happen during the next protected theme operation.

The apply transaction

validate -> stage -> backup -> apply -> verify -> commit
                 \                         /
                  ------ roll back -------

Validate

The Helper checks the device and access decision, package signature and content, official Codex identity, loopback endpoint, and required interface capabilities. A failure here leaves the current appearance untouched.

Stage

The verified package is downloaded and unpacked into a constrained staging area. It is not treated as executable input.

Backup

Before the first visual mutation, Codex Skin stores the exact native appearance choice that existed before the first apply: system, light, or dark, plus the related native code-theme setting. This recovery point lives outside the Plugin cache and remains until Restore.

Apply

A dark skin pins the native Codex appearance to dark; a light skin pins it to light. If the native mode already matches, the Helper does not rewrite it or restart. A trusted same-mode theme replacement can happen in the current window.

On macOS, a verified in-app Appearance path is tried first for a dark/light change. If that contract is absent before mutation, the operation can fall back to one explicitly confirmed controlled restart. Windows currently keeps that confirmed restart path for a mode change. The theme itself cannot control either path.

Verify and commit

The Helper verifies the exact requested public ID and version in the current official renderer, along with the required visual markers. Only then does it commit the operation as successful. If apply or verification fails, it restores the previous verified state or the saved official appearance instead of leaving a half-applied theme.

Why visible verification is the success boundary

Several valid intermediate events can occur without proving that the user sees the requested theme. An API may return 200, a package may download, the style layer may be inserted, or a restart may be accepted. None of those is the final result.

For a direct operation, success is one structured response with ok: true, the requested themePublicId, a themeVersion, and an operationId. For a controlled restart, status must reach completed and match the requested theme ID and version. desired, downloaded, pending_confirmation, restart_approved, and running are not success.

Local history has the same limit. appliedThemePublicId means the last bounded operation committed after visible verification. It cannot prove that a renderer created after a full quit or later reload still has the theme.

Failure, rollback, and Restore

Failure behavior depends on when the operation stopped:

A download, descriptor, signature, hash, content, identity, or capability failure before mutation does not touch the current appearance.
A failure after mutation uses the transaction backup to restore the previous verified state or official appearance.
An uncertain process, renderer, or ownership check stops new apply work instead of guessing.
A stable error code points to one next action without exposing tokens, storage keys, stack traces, or sensitive local paths.

Offline Restore removes the skin and restores the exact native appearance saved before the first apply. It does not require network access, login, active Pro access, Node, or the Plugin cache. That recovery path stays available when an apply fails, access expires, a refund is confirmed, or the Plugin is removed.

Session boundary and local state

The current Paid Alpha uses one-shot transactions. After apply, switch, or Restore finishes, the Helper exits. There is no runtime marked active, no heartbeat keeper, and no Guardian or service that silently re-injects the theme.

Completely quitting Codex, restarting the computer, or a later renderer reload ends the current visible guarantee. The user can ask the Plugin to apply a theme again. Last verified status and the out-of-cache recovery point remain useful local facts, but they are not a promise that the current renderer is still themed.

What the architecture deliberately excludes

Codex Skin does not accept arbitrary theme code, remote commands, custom origins, or user-provided selectors. It does not install a persistent MCP process, system service, daemon, tray or menu app, login item, or startup injector for theme persistence.

It does not modify the official Codex application package, app.asar, code signatures, WindowsApps files, or protected system directories.

By default, product and Helper records exclude prompts, conversations, source code, project files, absolute paths, tokens, cookies, and screenshots. The bounded records needed for delivery and support use identifiers, versions, timestamps, byte counts, results, and stable errors rather than workspace content.

Questions

Does Codex Skin modify the Codex application package?

No. It operates a verified official Codex process through short-lived loopback control and fixed local rendering rules. Official packages, signatures, and protected files remain unchanged.

Why use a Helper instead of running everything in the Plugin?

The Helper provides a self-contained, signed, platform-specific boundary for credential storage, package verification, official process checks, transactional backup and rollback, and offline Restore. The Plugin remains a small intent and user-interaction layer.

Does Codex Skin run in the background after a theme is applied?

No. The Helper exits after the current result is verified. A later full quit, computer restart, or renderer reload requires the user to apply the theme again.

To use the public entry point, install the Plugin. For a first theme, follow Quickstart. For the user-facing risk model, read Safety and compatibility.