Describe exactly what is and is not visible
Begin with the smallest factual description. Does official Codex open? Is the theme absent on both home and task views, visible only on home, visible only in one existing window, or replaced by a blank or partly styled layout? Did the helper report success, show an error, or close without readable output? Record the launcher or command used, the page open at the time, window size, and whether the problem began on first setup or after an update. Avoid the vague statement that it does not work. Different visible outcomes point to source, process, target selection, responsive styling, image preparation, or compatibility, and each category needs a different check.
- Official app launch result.
- Home versus task behavior.
- Exact launcher and visible output.
- First install versus post-update failure.
Restore and establish an official-app baseline
Use the documented restore path before deeper troubleshooting, then open Codex through its ordinary official entry point. Confirm that projects, authentication, navigation, tasks, and composer work without the third-party visual layer. If the official app is already broken, solve or report that baseline problem before changing theme files. A healthy baseline separates a styling failure from an app installation, account, or operating-system issue. Preserve logs and state until restore has run; deleting them first removes the helper’s record of its session. Once the baseline is clear, quit official Codex normally so the reviewed launcher can start from a known state.
- Run documented restore before manual cleanup.
- Open official Codex independently.
- Verify normal tasks and controls.
- Quit cleanly before another launch attempt.
Confirm source, version, and launch entry
Return to the original repository rather than a copied archive or old blog attachment. Compare the checkout with the current platform README, review recent changes, and name the commit used. On Windows, verify the Store app and documented Node.js requirement. On macOS, verify processor architecture, official app location, and the exact .command or script entry. If a launcher closes immediately, run only its reviewed underlying script in a terminal to retain output. Do not compensate by disabling security, running unrelated binaries, or granting broad permissions. A provenance or prerequisite failure should be fixed at its source instead of being hidden by repeated administrator execution.
- Use the original repository and current platform directory.
- Record the commit and prerequisite versions.
- Read terminal output from the reviewed script.
- Do not bypass warnings or broaden permissions casually.
Check that the intended Codex window is the target
A local runtime styling workflow must connect to the expected official Codex renderer. Existing windows, stale helper state, multiple app instances, or another local debugging process can make target selection ambiguous. Close extra Codex windows and unrelated helper copies, then use the normal launcher’s documented behavior. If a local port is occupied, identify its owner rather than terminating arbitrary applications. Run the platform verify or doctor tool and keep its text output. A report that the app opened is not enough; evidence should show whether the expected endpoint and renderer were found and whether styling reached home and task surfaces.
- Close duplicate windows and helper copies.
- Identify rather than guess about local ports.
- Use verify or doctor output.
- Check both renderer surfaces explicitly.
Separate image preparation from runtime styling
If panels or accent colors change but the background does not, the runtime layer may be active while image preparation or configuration failed. Test with a rights-cleared, modest PNG or JPEG copy that meets documented platform limits. Avoid using a valuable original during diagnosis. Check whether the selected file was processed, where the project says the prepared asset belongs, and whether the applied theme references the current copy rather than an older path. If the background appears but text becomes unreadable, that is a composition problem, not proof that the helper failed. Use the composition and contrast guides after technical visibility is confirmed.
- Use a simple licensed PNG or JPEG copy.
- Check documented format and size limits.
- Confirm the active theme references the intended asset.
- Treat readability separately from visibility.
Handle updates and submit useful evidence
When a theme worked before an official Codex update, restore first, confirm the new official app works, then compare current upstream compatibility notes. Reinstall or reapply only as documented for the current source. Do not mix old installed files with newly downloaded launchers without reviewing migration behavior. If the issue remains, report operating system, processor architecture, official app distribution, source commit, exact launcher or command, sanitized verify output, and whether the problem affects home, task, or both. Remove usernames, tokens, private paths, project names, and task content. Documentation errors belong to CodexSkin; runtime behavior belongs to the upstream issue tracker.
- Separate Codex and helper update timelines.
- Report exact environment and source state.
- Sanitize diagnostics before posting.
- Send the issue to the responsible project.