---
name: codetheme-theme-installer
description: Download, validate, apply, inspect, roll back, or restore published Codex desktop themes through Codex Theme's public, reversible workflow.
argument-hint: "<theme id or CodexThemes theme URL | list | status | apply <id> | rollback | restore>"
user-invocable: true
---

# Codex Theme skill entrypoint

This is the public entrypoint for Codex Theme. Download it directly from:

`https://codetheme.org/SKILL.md`

It is intentionally distributed from this site, not through a repository install command. Use this workflow only for the Codex Theme runtime and its published helper files.

## What this Skill can do

| Your goal | What to use |
| --- | --- |
| Install a published theme | `install-theme.mjs <theme id or /themes/ URL>` |
| See themes already available locally | `switch-theme.mjs list` |
| Check which theme is active in a running Codex window | `switch-theme.mjs status` |
| Apply an installed theme | `switch-theme.mjs apply <theme-id>` |
| Return to the prior managed theme | `switch-theme.mjs rollback` |
| Return to Codex's native appearance | `switch-theme.mjs restore` |

Use a published lower-case theme ID (for example `caishen-lite`) or a `https://codexthemes.ai/themes/<id>` detail URL. A `/skins/<id>` page is design inspiration only: do not guess a package ID from it or try to install it. Ask for a published theme page instead.

## Prepare the public helper bundle

This downloaded entrypoint is the instruction file. The executable helpers are separately published on the same site, so they can be obtained without exposing or using a source repository. Before running a command, place the three helper files together in a private local directory outside the current workspace:

```bash
SKILL_DIR="${CODEXTHEMES_HOME:-$HOME/.codexthemes}/tools/codetheme-theme-installer"
mkdir -p "$SKILL_DIR/scripts"

curl --fail --location --silent --show-error \
  https://codetheme.org/skills/codetheme-theme-installer/scripts/paths.mjs \
  -o "$SKILL_DIR/scripts/paths.mjs"
curl --fail --location --silent --show-error \
  https://codetheme.org/skills/codetheme-theme-installer/scripts/install-theme.mjs \
  -o "$SKILL_DIR/scripts/install-theme.mjs"
curl --fail --location --silent --show-error \
  https://codetheme.org/skills/codetheme-theme-installer/scripts/switch-theme.mjs \
  -o "$SKILL_DIR/scripts/switch-theme.mjs"
```

Keep `SKILL_DIR` set to that directory whenever you run the commands below. Do not copy themes, helper scripts, temporary packages, or generated previews into the current project workspace.

## Managed local storage

The Skill keeps its own files under `~/.codexthemes/` by default:

- Theme packages: `~/.codexthemes/themes/<theme-id>/`
- Runtime state: `~/.codexthemes/state/codetheme-runtime.json`
- Helper files: `~/.codexthemes/tools/codetheme-theme-installer/`

Set `CODEXTHEMES_HOME` only when you need a different private library root. The Skill never uses the current workspace as a fallback theme directory.

## Install a published theme

Start by checking the current state. Then install the selected published package:

```bash
node "$SKILL_DIR/scripts/switch-theme.mjs" status
node "$SKILL_DIR/scripts/install-theme.mjs" caishen-lite
```

Installing an already-present theme preserves its local package. Use `--force` only when you intentionally want to replace it with the latest published copy:

```bash
node "$SKILL_DIR/scripts/install-theme.mjs" caishen-lite --force
```

The downloader accepts only a supported ID or an official theme detail URL. It limits downloads, checks the package manifest and ID, permits only safe package-relative assets, rejects remote or executable CSS constructs, and keeps package content within the managed library. These checks reduce common package risks; they are not a signature, malware scan, or guarantee of publisher provenance.

## Apply and confirm a theme

List the installed packages if you need to choose one, then apply it:

```bash
node "$SKILL_DIR/scripts/switch-theme.mjs" list
node "$SKILL_DIR/scripts/switch-theme.mjs" apply caishen-lite
node "$SKILL_DIR/scripts/switch-theme.mjs" status
```

When Codex exposes an eligible local debugging endpoint, the Skill applies the visual layer to the running Codex renderer and then checks the real page before reporting success. It probes the requested port and the usual local ports (`9335`, `9222`, and `9223`). If a nonstandard local endpoint is already known, provide it explicitly:

```bash
node "$SKILL_DIR/scripts/switch-theme.mjs" --port 9335 apply caishen-lite
```

If the result says `restart-required`, explain that hot-swap is unavailable. Ask the user before a restart. Only after they explicitly agree may you use the documented macOS relaunch path:

```bash
node "$SKILL_DIR/scripts/switch-theme.mjs" apply caishen-lite --launch
```

`--launch` schedules the relaunch rather than claiming that the theme is already active. Follow it with `status`; success means the requested ID is reported as active. Automatic relaunch is macOS-only and requires `/Applications/Codex.app`. On other platforms, tell the user how to start Codex with a local debugging port rather than attempting an unapproved workaround.

## Switch, roll back, or restore

Use the same validation loop after every visual change:

```bash
node "$SKILL_DIR/scripts/switch-theme.mjs" status
node "$SKILL_DIR/scripts/switch-theme.mjs" apply <theme-id>
node "$SKILL_DIR/scripts/switch-theme.mjs" status
```

The runtime records one prior managed theme. To return to it:

```bash
node "$SKILL_DIR/scripts/switch-theme.mjs" rollback
node "$SKILL_DIR/scripts/switch-theme.mjs" status
```

To remove the Codex Theme visual layer and return to native Codex:

```bash
node "$SKILL_DIR/scripts/switch-theme.mjs" restore
node "$SKILL_DIR/scripts/switch-theme.mjs" status
```

`restore` removes only the style element and state marker owned by this Skill. It keeps downloaded packages so they can be applied later. If Codex cannot be reached, treat the result as unverified and keep state intact; do not claim the appearance was restored until a reachable `status` check confirms it.

## Copyable requests for Codex

Use these as concise, safe user requests:

```text
Download and use the Codex Theme Skill from https://codetheme.org/SKILL.md. Install the published theme "caishen-lite", check its status, then apply it only if Codex is reachable through a local debugging endpoint. Ask me before any restart. Confirm the active theme with status and tell me how to rollback or restore the native look.
```

```text
Use the Codex Theme Skill from https://codetheme.org/SKILL.md to list my installed themes and apply "<theme-id>". Do not restart Codex without my explicit approval. Verify the running window before saying it worked.
```

```text
Use the Codex Theme Skill from https://codetheme.org/SKILL.md to restore Codex's native appearance. Do not modify application files. Report the result of the runtime status check.
```

## Safety rules

- Never edit `app.asar`, signed application files, `WindowsApps`, authentication data, user tasks, or global system stylesheets.
- The only live visual change is an owned `<style>` element injected through Codex's loopback debugging endpoint. Fully quitting Codex clears that session-only layer.
- Ask before restarting Codex, changing settings, or fetching any package that the user did not identify.
- Never report installation as application. Installation adds a local package; only a successful runtime `status` check proves the requested theme is active.
- A failed or partial apply must attempt recovery to the prior managed theme or native appearance and report the outcome instead of silently leaving a mixed state.
- Never treat a skin reference or an arbitrary URL as an installable package.

## Honest limits

This public Skill does not browse a catalog, create themes, import arbitrary local archives, delete packages, or submit themes to a gallery. It also does not provide a persistent native theming system: a compatible local debugging endpoint is required for live application, and a new Codex session may require applying the theme again.

Published packages originate from their publisher. The local validation is deliberately conservative, but it cannot establish cryptographic authenticity or make third-party content safe in every context. Review the published theme page before applying it.

## If a command cannot continue

- **A skin URL was provided:** explain that it is a visual reference and request a published `/themes/<id>` URL or ID.
- **No local debugging endpoint is reachable:** install the package if requested, report `restart-required`, and ask whether the user wants the approved restart path.
- **`status` is not active after a restart:** do not claim success; report the observed state and offer `apply`, `rollback`, or `restore`.
- **A package is rejected:** preserve the existing installed package, show the validation reason, and do not bypass the checks.

The public source of truth is always this site: `https://codetheme.org/SKILL.md`.