Back to home

Install Guide

How to install Codex skins and desktop pets — free, no account required.

Last updated: 2026-07-31

Installing Codex Skins

Step 1: Install Dream Skin

Dream Skin is a free, open-source tool that applies themes to the Codex desktop app.

Download the latest version from GitHub Releases:

  • macOS — download the .dmg, open it, drag to Applications
  • Windows — download the .exe installer, run it

After installation, a menu bar icon (macOS) or system tray icon (Windows) appears.

First time? Make sure you've installed and opened the official Codex desktop app at least once before using Dream Skin.

Developer install (from source)

Clone the repository, then:

  • macOS: open macos/, double-click Install Codex Dream Skin.command
  • Windows: run powershell -ExecutionPolicy Bypass -File .\windows\scripts\install-dream-skin.ps1

Step 2: Get a theme

Browse the Skin Gallery and pick a theme you like.

Step 3: Apply the theme

Option A — One-click apply (recommended)

On the skin detail page, click the "One-Click Apply" button. This opens Dream Skin and applies the theme automatically.

Requires Dream Skin v1.5.5 or newer. The app will show a confirmation dialog, verify the theme's integrity (SHA-256), and then apply it.

Option B — Import theme ZIP

  1. Click "Download ZIP" on the skin detail page
  2. Open Dream Skin from the menu bar / system tray
  3. Click "Import Theme…" and select the downloaded ZIP
  4. The theme appears in your Saved Themes list
  5. Select it and click Apply

Note: importing a ZIP adds it to your theme library — it does not auto-apply. You need to select and apply it manually.

Restore original look

Open the Dream Skin menu and click "Restore" at any time to return to the default Codex appearance.

Safety

  • Dream Skin uses Chrome DevTools Protocol (CDP) bound to 127.0.0.1 only — no network exposure
  • Does not modify .app, app.asar, or code signatures
  • Does not change your API keys or model provider settings
  • Theme ZIPs are capped at 32 MiB, CSS is validated, all files are SHA-256 checked
  • After a Codex update, restore first, then verify

Installing Codex Pets

Step 1: Copy the install command

On any pet's detail page, you'll find a ready-to-paste install command. Or use these templates:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- <pet-id>

Windows (PowerShell):

powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -UseB https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.ps1 | iex; Install-CodexPet <pet-id>"

Replace <pet-id> with the pet's slug, e.g. firefly--lingxiaotian.

Step 2: Run it

Open your terminal (or PowerShell on Windows), paste the command, and press Enter.

The script downloads two files into ~/.codex/pets/<pet-id>/ (or %USERPROFILE%\.codex\pets\<pet-id>\ on Windows):

  • pet.json — metadata
  • spritesheet.webp — animation frames

That's all it does. It does not modify the Codex app, your config, or any other files.

Step 3: Activate the pet

  1. Quit and reopen the Codex desktop app
  2. Go to Settings → Pets
  3. Find the pet you just installed
  4. Select and enable it

The install command only places files on disk. Codex discovers new pets by scanning the pets directory, so you need to restart it.

Multiple pets

You can install as many pets as you like — each one lives in its own folder. Installing a new pet does not remove existing ones. Switch between them in Settings → Pets.

Removing a pet

Delete the specific pet's folder:

  • macOS/Linux: rm -rf ~/.codex/pets/<pet-id>/
  • Windows: Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\pets\<pet-id>"

Then restart Codex. Do not delete the entire ~/.codex/pets/ directory — that would remove all your pets.

Privacy note

The install script sends a single anonymous install-count ping to the pet registry after a successful install. No personal data is collected. To opt out:

AWESOME_CODEX_PET_NO_STATS=1 curl -fsSL https://raw.githubusercontent.com/legeling/awesome-codex-pet/main/scripts/install-pet.sh | bash -s -- <pet-id>

v1 vs v2 pets

  • v1 — standard animation set (idle, walk, wave)
  • v2 — expanded animations with more states and smoother transitions

Both install and activate the same way. v2 just has more animation frames.