Install a Codex theme from CodexThemes

Download a published theme's portable package from codexthemes.ai and unpack its source files into ~/.codexthemes/themes/<theme-id>/. This skill is standalone: its TypeScript scripts own the download, validation, and local installation. It does not search the gallery (codex-theme-finder), create themes (codex-theme-creator), or submit them (codex-theme-submitter). Applying belongs to codex-theme-switcher — but a successful install chains directly into it (Step 4); installing files and stopping is not a finished job. The only required local tools are Node.js 20+ and npx.

Read references/download-api.md before diagnosing an unexpected API response or changing endpoint behavior. Run all commands from the installed skill directory.

Step 1: identify the theme

Resolve what to install to a theme id — the lowercase slug from codex-theme-finder results or from a https://codexthemes.ai/themes/<theme-id> URL. The script accepts either form. If the user only describes a style without naming a theme, find candidates with codex-theme-finder first instead of guessing ids.

Step 2: install

npx tsx scripts/install-theme.ts <theme-id | codexthemes.ai theme URL> [--force]

Downloads work without any API key inside a free anonymous quota, so do not demand a key up front. When a key is already configured (CODEXTHEMES_API_KEY environment variable or ~/.codexthemes/credentials.json), the script sends it automatically for higher limits.

The script validates the downloaded package (format, schema version, matching theme id, safe relative filenames, ≤30 MB) before writing anything, then unpacks theme.json, the stylesheet, the artwork, and the readme into ~/.codexthemes/themes/<theme-id>/. It refuses to overwrite an existing non-empty theme directory; pass --force only after the user confirms replacing their local copy — the directory may hold their own edits.