get-codex-theme

Get Codex Theme CLI

Install, switch, validate, and safely restore portable themes for Codex Desktop. Node.js 22 or later is required.

npx -y get-codex-theme list
npx -y get-codex-theme use aurora-glass
npx -y get-codex-theme doctor

use installs and selects without restarting Codex. Run launch only when you want the unofficial loopback CDP compatibility layer, and add --restart only after deciding that the running Codex task may be closed.

Optional local controls are installed with a theme pack:

npx -y get-codex-theme menu-bar start   # macOS
npx -y get-codex-theme tray start       # Windows
npx -y get-codex-theme watchdog enable  # macOS, opt-in session supervision

The default Watchdog waits for a debug-enabled Codex session and restarts only the injector; it never launches or restarts Codex. Use pause for a temporary stock appearance or restore to remove the active pointer.

watchdog enable --persistent is a separate, explicit macOS opt-in. It defers the currently running Codex instance, then may restart a future normal launch once with the loopback theme arguments. Disable it with watchdog disable.

The visual compatibility runtime is unofficial. It binds only to loopback, does not patch the signed Codex application, and keeps restoration available.

Documentation and source: https://github.com/ViisOpen/get-codex-theme

Authoring paths

Run create with only a theme id from an interactive terminal to open the authoring wizard:

npx get-codex-theme create my-theme

The wizard explains three paths before it writes anything and recommends Assisted by default:

• Focused styles Foundation plus the component groups you select. Every required token in a selected group is generated; unselected groups inherit adaptive runtime defaults.
• Complete generates every supported component group.
• Assisted generates safe complete defaults from a palette and style preset. In the create wizard, a local source image is optional; providing one uses the same local-only pipeline as create-from-image.

Before creating the directory, the wizard shows the resolved name, mode, path, component selection or preset, output directory, and Codex app: Will not be modified. Answering No cancels normally without writing files.

For scripts and agents, provide the authoring path explicitly and add --non-interactive. Focused also requires --components. These invocations never prompt and fail clearly when a required authoring option is missing:

# Foundation plus selected groups
npx -y get-codex-theme create my-theme --name "My Theme" --mode dark \
  --path focused --components buttons,icons --output ./themes --non-interactive

# Every required token in all seven groups
npx -y get-codex-theme create my-theme --name "My Theme" --mode dark \
  --path complete --output ./themes --non-interactive

# Image-derived adaptive baseline, ready for targeted overrides
npx -y get-codex-theme create-from-image art.png my-theme --name "My Theme" \
  --mode dark --path assisted --preset soft --output ./themes --non-interactive

npx -y get-codex-theme coverage ./my-theme

When either stdin or stdout is not a TTY, incomplete authoring flags fail fast; the CLI never silently chooses Focused, Complete, or Assisted. Complete flags remain deterministic with or without a TTY. Theme creation only writes a draft pack and never launches, restarts, or injects Codex.

Themes contain bounded component tokens only. Raw CSS, HTML, JavaScript, selectors, and SVG paths are not accepted by the public validator.