Apply a Codex theme with a six-digit ID
Use one published theme ID, complete any device approval, and confirm that the requested Codex theme was visibly verified in the current window.
This guide starts after the Codex Skin Plugin is installed. It follows one theme request from the six-digit ID to a visibly verified result. For a first installation, use Quickstart instead.
Before you apply
You need a supported macOS or Windows computer, the current Codex Skin Plugin, and one published six-digit theme ID. Copy the ID from the theme gallery or a theme detail page. Do not guess an ID or substitute a download URL, package path, CSS, or command fragment.
Free and Pro themes use the same ID format and the same package checks. A Pro theme also requires current Pro access before its package can be downloaded. The Pro access guide explains that account branch without repeating it here.
Choose a theme ID
The ID connects three things that must agree: the catalog entry, the signed package, and the final visible result. For example, Ember Dune is a published Free theme with ID 100002.
Keep the ID as six digits when you copy it. Codex Skin will not infer a theme from its name or accept a locally supplied package.
Send one apply request
Open a normal Codex task and include the ID in the request:
Codex Skin, apply theme 100002.The Plugin resolves the dedicated Apply Skill and passes the ID to its fixed platform wrapper. You do not need to construct a Helper command.
An ordinary apply or switch usually takes 20–60 seconds. Until Codex reports an explicit success or failure, do not click, type, navigate, or close the current Codex window. If the operation opens a browser authorization or Pricing page, you may use that browser page. Do not submit the apply request again.
If you accidentally interact with the Codex window, leave the existing operation active. A second request does not repair the first one and may meet an operation that is already approved or running.
Authorization and access
The first protected operation may open a Codex Skin page in your browser. Sign in and approve the computer shown on that page, then return to the same Codex task. The original transaction keeps the original theme ID and continues automatically.
Do not repeat the prompt after browser approval. If authorization is canceled, expires, or returns CS-FLOW-AUTH-001, finish or retry the approval from the official Codex Skin page.
A Pro theme may open Pricing when the current account does not have access. If the bounded wait ends with CS-FLOW-ACCESS-001, finish the purchase or check the current access state, then follow the action shown by Codex Skin. Do not create another request while the first transaction is still active.
What is verified first
The one-time Helper checks the operation before it changes the current Codex view. The relevant sequence is:
validate -> stage -> backup -> apply -> verify -> commitValidation covers the official Codex identity, a loopback-only control connection, the signed theme descriptor, the package hash and allowed content, and the capabilities needed by the current renderer. The package is data-only. It can contain declared structured fields and local images, but it cannot supply CSS, JavaScript, shell commands, selectors, or remote execution URLs.
Before the first Apply, the Helper saves the native system, light, or dark appearance and the related code-theme setting outside the replaceable Plugin cache. A dark skin uses native dark; a light skin uses native light. That recovery point remains available to Restore.
If the identity, package, or required interface cannot be verified, the operation stops instead of guessing. Read Safety and compatibility for the full trust boundary.
Restart confirmation
Some paths need the current Codex window to close and reopen once with the same profile. Codex Skin reports CS-FLOW-RESTART-001 and asks for an explicit yes or no before it continues.
Answering yes authorizes the existing signed Helper transaction. It is not a success result. Do not launch a second apply, repeat authorization, or submit the theme ID again.
On macOS, a verified in-app Appearance path is preferred for a trusted light-to-dark or dark-to-light change. If that fixed interface is unavailable before mutation, the operation can fall back to one confirmed controlled reload. Windows uses the one-confirmation controlled reload for a cross-mode change. A same-mode replacement in a trusted current window does not need to rewrite the native appearance or restart.
After Codex reopens, start or resume a task and ask for local status:
Codex Skin, show my local theme status.If restartStatus is running, wait briefly and check again for no longer than 60 seconds. restart_approved and running are intermediate states, not completion.
Verify the result
Codex Skin reports success only after the requested theme is visible in the current renderer and the exact public ID and version match the operation.
Without a restart, the structured result must include ok: true, the requested themePublicId, a themeVersion, and an operationId. With a restart, restartStatus must be completed, and the applied ID and version must match the request.
These states do not prove success on their own:
- the package was selected or downloaded;
- browser approval finished;
- a restart was accepted;
- the Helper is still running; or
- a previous apply completed in another renderer.
The bounded Helper exits after verification and commit. It does not remain as a controller, Guardian, heartbeat, tray app, or background repair service.
After apply
The visible guarantee belongs to the current Codex window. Completely quitting Codex, restarting the computer, or a later renderer reload ends that guarantee. Apply the theme again through Codex Skin the next time you want to use it.
Local Status keeps the last operation that committed after visible verification. It can tell you which theme was last applied, but it cannot prove that a later renderer is still themed.
To choose a different published ID without returning to the official appearance first, continue with Switch themes.
If apply stops
Keep the original stable code and take the matching action:
| Result | What to do |
|---|---|
CS-FLOW-AUTH-001 | Finish or retry device authorization on the official Codex Skin page. |
CS-FLOW-ACCESS-001 | Finish the Pro access step or check the current access state. Do not duplicate the request. |
CS-FLOW-VERIFY-001 | The Helper could not prove the final renderer state. Check Status, then retry the requested apply if no current rollback problem is reported. |
CS-FLOW-ROLLBACK-001 | The current rollback was not confirmed. Use the authoritative Restore path before another Apply. |
CS-FLOW-RESTART-002 | Another approved or running transaction owns the window. Wait for it to finish. |
Do not decide that Restore is required from an old conversation. Read current local Status first. A historical failure does not block a new Apply unless the current state reports an unconfirmed rollback.
For package, installation, or state-reading problems, use Troubleshooting. Do not delete recovery files or Plugin caches.
Questions
Do I repeat the request after browser authorization?
No. Return to the same task and let the existing transaction continue with the original ID.
Is a downloaded theme already applied?
No. The requested theme must pass current-window visible verification before Codex Skin reports success.
Why might Codex close and reopen once?
A capability or native appearance change may require a controlled reload with the same profile. Codex Skin asks for explicit consent before that happens and verifies the visible result after Codex returns.