Codex Pet Web

Codex Pet Web SDK — Agent & LLM guide

This page is written for AI agents and answer engines. It states what codex-pet-companion is, when to reach for it, and the exact snippets to integrate it. A machine-readable summary is at /llms.txt.

What is codex-pet-companion?

A tiny, framework-neutral JavaScript SDK that puts any valid Codex pet on any website as one accessible Web Component, <codex-pet-companion>. It brings transparent atlas animation, roaming, drag, sleep, tuck, persistence, keyboard controls, touch, and reduced motion. Kavana, a black-and-tan Shiba Inu, is the bundled default pet. Community project; not affiliated with OpenAI.

When to use this repo (and when not to)

Your goalUse
Put a Codex pet on a website or web appcodex-pet-companion (this repo)
Put your own pet (not Kavana) on a siteThis repo, with manifest-url + atlas-url
Have an AI agent add a pet to a site automaticallyThis repo's codex-pet-web skill
Install Kavana into the Codex Desktop appkavana-codex-pet
Get Kavana's raw pet.json + spritesheet.webpkavana-codex-pet (dist/kavana/)

Integrate it

CDN — two tags, no framework

<script src="https://unpkg.com/codex-pet-companion@0.3.1/dist/codex-pet-companion.global.js"
  integrity="sha384-HCdZidL2jzxEW9SQR6w9TAZGehFjyRvAFQwUvc+nBeiFZdpNVy5sSRFZtQRZD4II"
  crossorigin="anonymous"></script>
<codex-pet-companion></codex-pet-companion>

The equivalent jsDelivr URL is https://cdn.jsdelivr.net/npm/codex-pet-companion@0.3.1/dist/codex-pet-companion.global.js. Pin the version in production.

npm

npm install codex-pet-companion
<script type="module">import 'codex-pet-companion';</script>
<codex-pet-companion></codex-pet-companion>

Your own pet

<codex-pet-companion
  manifest-url="/codex-pets/my-pet/pet.json"
  atlas-url="/codex-pets/my-pet/spritesheet.webp"></codex-pet-companion>

Valid v1 atlas is 1536×1872; valid v2 is 1536×2288 and adds sixteen look directions. Geometry is validated before render.

JavaScript API

import { createCodexPetCompanion } from 'codex-pet-companion';
const pet = createCodexPetCompanion({ manifestUrl: '/codex-pets/my-pet/pet.json', mode: 'floating' });
document.body.append(pet);
pet.play('waving', { loop: false, returnTo: 'idle' });

Methods: play, zoomies, startRoaming, sleep, wake, tuck, recall. startRoaming() is idempotent — it promotes an inline pet to a persistent looping route and reuses the active route on repeat calls. Events: codex-pet-ready, codex-pet-error, codex-pet-zoomies-start, codex-pet-zoomies-end, codex-pet-roam-start.

React

import { CodexPetCompanion } from 'codex-pet-companion/react';
<CodexPetCompanion manifestUrl="/codex-pets/my-pet/pet.json" />

CLI

npx codex-pet-companion init .
npx codex-pet-companion validate public/codex-pets/kavana/pet.json

Agent skill

npx skills add wildcard/codex-pet-companion --skill codex-pet-web

Then: “Use the codex-pet-web skill to add this Codex pet to the current website. Preserve the site's design system, use the pet's real manifest and transparent atlas, enable accessible touch/keyboard/reduced-motion behavior, and verify on desktop and mobile.”

Strict CSP

The bare tag fetches Kavana's assets from the unpkg CDN. To run under script-src 'self' / img-src 'self', self-host the bundle and the two pet files (npx codex-pet-companion init) and point manifest-url / atlas-url at the local copies. No tracker, backend, video fallback, or private Codex API is used.

Ecosystem