CPCodex Pets Tool

How to install Codex pets

Put the package where Codex expects it.

A Codex pet is a folder with a manifest and a spritesheet. Once the folder is installed, use /pet inside Codex to show or hide the companion.

Folder contract

Local package shape

~/.codex/pets/my-pet/
  pet.json
  spritesheet.webp

The manifest identifies the pet and points Codex to the spritesheet file inside the same package folder.

pet.json

Minimum manifest

{
  "id": "my-pet",
  "displayName": "My Pet",
  "description": "A concise pet description.",
  "spritesheetPath": "spritesheet.webp"
}

Atlas

Spritesheet dimensions

1536 x 1872 px8 columns x 9 rows192 x 208 px cells

The animation rows are idle, running right, running left, waving, jumping, failed, waiting, running, and review.

Local install snippet
mkdir "$HOME/.codex/pets/tater"
cp pet.json "$HOME/.codex/pets/tater/pet.json"
cp spritesheet.webp "$HOME/.codex/pets/tater/spritesheet.webp"

# In Codex
/pet

How to use

How to install a Codex pet

  1. 01

    Create the pet folder

    Make a dedicated ~/.codex/pets/<pet-id>/ directory so Codex can discover the package by id.

  2. 02

    Add the required files

    Place pet.json and spritesheet.webp in that folder, keeping the manifest id aligned with the folder name.

  3. 03

    Confirm the atlas contract

    Use a 1536 by 1872 spritesheet with 8 columns, 9 rows, 72 frames, and 192 by 208 frame cells unless your renderer contract changes.

  4. 04

    Activate it in Codex

    Restart or refresh Codex if needed, then use /pet to select the installed Codex pet.

Install FAQ

Codex pet installation questions

Where do custom Codex pets go?

Custom Codex pets go under ~/.codex/pets/<pet-id>/. The folder should contain pet.json and spritesheet.webp, with the manifest spritesheetPath pointing to the image file.

How do I turn on the pet after installing it?

Use /pet inside Codex after the package is in the local pets folder. If the custom pet does not appear, confirm the folder name, pet.json id, and spritesheetPath all match the installed files.

Can spritesheetPath be an external URL?

For local Codex installation, spritesheetPath should point to the image file inside the pet folder. For web preview, this tool can load a browser-accessible URL because the React renderer only needs an image src.

What causes a Codex pet preview to look broken?

The most common cause is an image that does not follow the shared atlas dimensions. Check that the spritesheet is 1536 x 1872, uses 8 columns and 9 rows, and keeps each frame aligned to 192 x 208 cells.