OpenPets for Codex

Community-made animated companions for the native Codex desktop pet system.

This repository is intentionally small and contributor-first: each pet is a self-contained folder, the Python tool explains validation failures in plain language, and CI checks the same package that Codex loads locally.

Important

OpenPets for Codex is an independent community project. It is not affiliated with or endorsed by OpenAI, the unrelated OpenPets project, or the owners of any third-party characters.

Included pets

Pet	Preview	Notes
Pixel 星野爱 (hoshino-ai)	See pets/hoshino-ai	Unofficial, AI-assisted fan art; separate asset terms apply.
Kneeling Sam Altman (sam-altman)	See pets/sam-altman	Unofficial public-figure caricature; separate likeness terms apply.
Pixel Makise Kurisu (makise-kurisu)	See pets/makise-kurisu	Unofficial, AI-assisted fan art; separate asset terms apply.
Pixel Tayama (tayama)	See pets/tayama	Unofficial, AI-assisted fan art; separate asset terms apply.

Install a pet

One click (Codex Desktop)

Install Pixel 星野爱 in Codex

Install Kneeling Sam Altman in Codex

Install Pixel Makise Kurisu in Codex

The links are pinned to the v0.2.0 tag. Codex previews and validates a package before installing it. App-managed one-click installs may use an app-derived local folder name, so openpets doctor is intended for CLI installs. Use the same method to update a pet. If your browser does not open custom links, use the catalog CLI below.

Catalog CLI

You need Python 3.10 or newer.

git clone https://github.com/supdub/openpets-codex.git
cd openpets-codex
python -m venv .venv

Activate the environment and install the small CLI:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
openpets list
openpets install sam-altman  # Replace with any listed pet ID.

# macOS or Linux
source .venv/bin/activate
python -m pip install -e .
openpets list
openpets install sam-altman  # Replace with any listed pet ID.

Then open Codex Settings → Pets, choose Refresh, select the pet, and choose Wake Pet. You can also type /pet in Codex. See the full installation guide for manual copying, WSL, updates, and troubleshooting.

Add your own pet

python -m pip install -e ".[dev]"
openpets scaffold my-pet --display-name "My Pet" --description "A tiny companion for long coding sessions." --author "Your name"

Use the generated source/atlas-guide.png as a layout guide, save the final spritesheet.webp beside pet.json, update the asset notice and provenance, then run:

openpets preview my-pet
openpets validate my-pet --strict
pytest

Start with Creating a pet, then read CONTRIBUTING.md. No application code change is required to submit a new pet.

Useful commands

Command	Purpose
openpets list	Show the catalog.
openpets validate --all --strict --check-registry	Run the CI-grade checks.
openpets preview <id>	Build a contact sheet and animation GIFs.
openpets preview --all --check	Verify committed previews match fresh renders.
openpets install <id>	Atomically install a validated pet.
openpets doctor <id>	Confirm the installed files match the repository.
openpets uninstall <id>	Remove a custom pet safely.
openpets scaffold <id> ...	Start a contribution from a guide.
openpets registry	Regenerate pets.json.

Project scope

The repository targets the native Codex desktop v2 spritesheet contract. It does not patch Codex, inject UI, run background services, or add custom interaction hooks. See the architecture and compatibility policy.

Code and documentation are MIT licensed. Pet artwork has per-pet terms and does not automatically inherit the code license; see ASSET_POLICY.md.