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. Reinstalling an existing pet id requires --force.

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 pet, install it with npm or ChatGPT, then enable it in Codex Settings. Node.js 20+ is required.

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 ChatGPT or the same npm command on macOS, Linux, and Windows.
3. Enable the pet
Restart Codex if it is open, then select the new pet under Settings → Pets.

Choose how to use the CLI

The installer downloads only pet.json and spritesheet.webp, verifies the repository manifest and SHA-256 hashes, then activates the package atomically. Replace the sample id with the exact id shown on the pet page.

Install with npm

Requires Node.js 20+ and npm on any platform.

npx --yes @legeling/codex-pet install <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 only pet.json and spritesheet.webp under pets/<pet-id>/. The installer also checks the SHA-256 hashes and WebP header before activation.

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 CLI.
Update or reinstall: Run the install command with --force to replace the same pet atomically. Other pets 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 with --force updates only that folder.