Where are custom Codex pets installed?

Each pet is installed under pets/ / in the Codex home directory, which is ~/.codex by default.

Why is my Codex pet not showing after installation?

Confirm that pet.json and spritesheet.webp exist, make sure pet.json.id matches the folder name, restart Codex, and reopen Settings → Pets.

Can Codex V1 and V2 pets be installed together?

Yes. The sprite version belongs to each pet package, so pets with different ids can coexist.

Install and activate

Bring a pet into Codex

Choose a selected pet, let ChatGPT install it or use the script for your system, then enable it from Codex Settings. The installer never touches your other pets.

Choose a pet Let ChatGPT install it

The shortest path

Every pet detail page already knows the exact pet id and prepares the right installation task for you.

1. Choose a pet
Open a detail page and preview the full action set before installing.
2. Pick a method
Use Open in ChatGPT, Bash, PowerShell, or the installer from a local clone.
3. Enable the pet
Restart Codex if it is open, then select the new pet under Settings → Pets.

Choose the method for your system

The installer copies only pet.json and spritesheet.webp into your Codex home. Replace the sample id with the exact id shown on the pet page.

macOS / Linux

Requires curl and bash.

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

Confirm the pet id

Use the complete pet-slug--author-slug value. The author suffix lets different versions of the same character coexist.

Run as your own user

No sudo or administrator shell is needed. A custom CODEX_HOME is supported when your setup uses another location.

Verify the two runtime files

A successful install contains pet.json and spritesheet.webp under pets/<pet-id>/.

Enable the pet in Codex

Installation places the files; Codex still needs to load and select the pet.

1
Restart Codex
If Codex was open during installation, quit and reopen it so the custom pet catalog refreshes.
2
Open Settings → Pets
Find the custom-pet section and confirm that the new id appears without an error badge.
3
Select the pet
Activate it, return to your workspace, and check idle, work, review, and movement states.

V1 and V2 install the same way

V1 pets contain nine standard action rows. V2 keeps those actions and adds 16 look directions. The atlas size and spriteVersionNumber differ, but the installer and destination do not.

Manage an installation

Default location: Pets are stored in ~/.codex/pets/<pet-id>/ on macOS and Linux, or %USERPROFILE%\.codex\pets\<pet-id> on Windows.
Custom Codex home: Set CODEX_HOME before the command, or pass --codex-home to the Bash and local Node.js installers.
Update or reinstall: Run the same command again with the same id. The two runtime files are replaced; other pet folders are left alone.
Uninstall: Quit Codex, remove only that pet's folder, then reopen Codex. No registry or system files are created.
Anonymous install count: Successful scripts send one anonymous install event. Set AWESOME_CODEX_PET_NO_STATS=1 to disable it.

FAQ

Open gallery →

Where are pets installed?

Each pet lands in your Codex home (default ~/.codex) under pets/<pet-id>/.

Can I uninstall a pet?

Delete the pet folder. Nothing else is touched.

Is sudo required?

No. Installs are scoped to your user directory.

The pet does not appear after installation. What should I check?

Confirm both runtime files exist, verify that pet.json.id matches the folder name, restart Codex, then look under Settings → Pets again.

Can V1 and V2 pets coexist?

Yes. Version belongs to each pet package. Different pet ids can coexist, and reinstalling one id updates only that folder.