Nyx

A sleepy charcoal cat for Codex. Nyx curls up with closed eyes while idle, walks in both directions, waves, reacts to task activity, and looks toward the pointer.

The artwork is drawn and animated directly in JavaScript using shared SVG shapes. Sharp renders those shapes into 73 transparent animation frames. No image generation is used.

Install

Download the pet package, or use the files in outputs/nyx.

1. Create a nyx folder under your Codex home directory's pets folder. The default location is ~/.codex/pets/nyx/. Back up any existing Nyx folder before replacing it.
2. Copy pet.json and spritesheet.png into that folder.
3. In Codex, open Settings → Pets, click Refresh, and select Nyx. Choose Wake Pet if the overlay is hidden.

Requires an app version that supports V2 custom pets. See the official pet guide.

Build and test

With Node.js 22 or later and pnpm installed:

set -euo pipefail
pnpm install --frozen-lockfile
pnpm build
pnpm test

Edit work/build_pet.cjs to change the character or poses. The build updates the sprite sheet, manifest, source copies, and sleeping GIF under outputs/. Intermediate SVG/PNG frames and a contact sheet are written under work/ and ignored by Git.

The validator checks the manifest, dimensions, alpha channel, frame occupancy, unused cells, unclipped margins, dark palette, and distinct frames. The sleeping GIF uses the app's six idle-frame timings for a 6.6-second loop. The app decides when each animation state plays.

The atlas is a 1536 × 2288 PNG: 8 columns and 11 rows of 192 × 208 cells. Its rows cover idle, walking right, walking left, waving, jumping, failed, waiting, working, review, and 16 pointer-looking directions. The geometry and timings were checked against the installed app's V2 implementation.

To refresh the downloadable archive after rebuilding:

set -euo pipefail
cd outputs
zip -q -r nyx-pet.zip nyx nyx-sleeping.gif