You do not need to Restore before an ordinary theme change. A switch is a new Apply transaction for a different published six-digit ID. It replaces the last verified theme only after the new package and current window pass their checks.

Before you switch

Choose a new ID in the theme gallery and make sure another theme operation is not already approved or running. Local history from an older failure does not require Restore. Check current Status if you are unsure.

You should Restore first only when the current state reports that rollback was not confirmed, or when you personally want to return to the official appearance before doing anything else.

Request the new theme

Include the new six-digit ID in one normal Codex request. For example:

Codex Skin, switch to theme 100005.

The same Apply Skill handles initial application and replacement. A Pro theme still requires current Pro access, but you do not repeat installation or device authorization when the existing state remains valid.

A 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. You may use a browser authorization or Pricing page opened by the transaction. Do not submit a second switch.

How the path is chosen

The Helper does not choose a path from the version number alone. It checks the official Codex identity, the loopback-controlled window, the current verified marker, the native appearance, and the capabilities required by the requested theme.

trusted current window
  -> same native mode: replace directly
  -> different native mode on macOS: verified in-app Appearance path
  -> in-app contract unavailable before mutation: ask for one controlled reload
  -> different native mode on Windows: ask for one controlled reload

Every branch uses a full signed package and ends with visible verification. A partial color change or a downloaded package is not a completed switch.

Same-mode switch

When the current controlled window is trusted and both themes use the same native mode, the Helper replaces the skin directly. A dark-to-dark or light-to-light change does not rewrite the native appearance and does not restart Codex.

Direct does not mean unchecked. The new package still passes signature, hash, content, identity, capability, and final visible-result checks.

Light and dark switches

On macOS, a trusted light-to-dark or dark-to-light change first uses the fixed in-app Appearance contract built into the signed Helper. The Helper verifies the live setting, native palette, current renderer, recovery point, profile, and loopback identity. If that interface is missing or ambiguous before any change, Codex Skin asks for one controlled reload instead.

If an in-app change becomes uncertain after mutation, the Helper first attempts to restore the original native mode. It stops without injecting the new skin when recovery cannot be confirmed.

Windows uses the one-confirmation controlled reload for a cross-mode change. The macOS path is not used as evidence that Windows can switch in place. Both platforms keep the exact native setting saved before the first Apply for later Restore.

Pending or running switch

The current operation state determines whether a new selection can replace it:

Current state	What happens to a new selection
`pending_confirmation`	A newly verified selection may replace the old unconfirmed request before renderer mutation.
`restart_approved`	The approved transaction owns the operation. Wait for it to finish.
`running`	The Helper is active. Do not preempt it or submit another request.
`completed` or terminal failure	Read current Status, then begin a new request if no rollback problem remains.

An approved or running operation returns CS-FLOW-RESTART-002 to a competing request. Waiting protects one transaction from being interrupted halfway through its cleanup and verification.

Restart confirmation

When a controlled reload is required, Codex Skin returns CS-FLOW-RESTART-001 and asks for yes or no. A yes authorizes one close-and-reopen operation with the same Codex profile. It does not mean that the new theme is already active.

Do not launch a second request after approval. Once Codex returns, ask for local Status. Success requires restartStatus: completed and the new public ID and version.

Verify the new theme

Without a reload, the switch succeeds only when one structured result contains ok: true, the requested themePublicId, a themeVersion, and an operationId. With a reload, the final Status must be completed and match the new ID.

The previous applied ID is historical once a new transaction starts. It cannot prove what the current renderer is showing. Likewise, an unconfirmed selection or a downloaded package is not the new active theme.

If the switch fails

Package rejection happens before the new skin is committed. Verification failure triggers the transaction's rollback path. Keep the stable error code and check current Status before deciding what to do next.

CS-FLOW-VERIFY-001 means the Helper could not prove the final renderer state. If current Status does not report a rollback problem, retry the requested switch.
CS-FLOW-ROLLBACK-001 means the current rollback was not confirmed. Use Restore before another theme operation.
CS-FLOW-RESTART-002 means another approved or running transaction must finish first.

Do not clear caches, edit the Codex application, or manually run an unknown Helper. Troubleshooting covers installation, authorization, package, restart, verification, and recovery states.

After switching

The bounded Helper exits after the new result is verified. Completely quitting Codex, restarting the computer, or a later renderer reload ends the visible guarantee. Apply the desired theme again through Codex Skin next time.

Current Pro access is required for a new Pro download, update, switch, or reapply. Expiry or refund does not remotely remove a skin that is already visible, and Restore remains available offline.

Questions

Do I need to Restore before every switch?

No. An ordinary switch is a replacement transaction. Restore is needed when you want the official appearance or current Status reports that rollback was not confirmed.

Does switching between light and dark always restart Codex?

No single answer fits every supported path. macOS prefers the verified in-app Appearance contract and falls back to one confirmed reload when that contract is unavailable before mutation. Windows uses the confirmed reload path for a cross-mode change.

Can I choose another theme while restart confirmation is waiting?

An unconfirmed pending request may be replaced by a new verified selection. Once a transaction is approved or running, wait for it to finish.