Codex Pet Web SDK

Put any valid Codex pet on any website with one Web Component. Kavana, the black-and-tan Shiba Inu from Project Caro, is included as the default.

Try the live field guide at pets.caro.sh and Kavana's real downstream integration at kavana.caro.sh.

This is a community project. It is not affiliated with or endorsed by OpenAI. Codex is an OpenAI product.

One-line CDN embed

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

The script defines <codex-pet-companion> and resolves Kavana from the same pinned npm package. Pin the version in production.

The equivalent jsDelivr URL is https://cdn.jsdelivr.net/npm/[email protected]/dist/codex-pet-companion.global.js.

The bare CDN element loads Kavana's default manifest and atlas from the same pinned CDN package. For a strict-CSP or fully self-hosted deployment, host the bundle and pet files yourself and provide both manifest-url and atlas-url as shown below.

npm

npm install codex-pet-companion

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

<codex-pet-companion></codex-pet-companion>

Strict-CSP note: the bare element still loads Kavana's pet.json and spritesheet.webp from unpkg. If your policy uses connect-src 'self' and img-src 'self', run npx codex-pet-companion init . and use the generated local manifest-url and atlas-url paths instead.

Use any Codex pet by serving its normal two-file package:

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

Valid v1 atlases are 1536×1872. Valid v2 atlases are 1536×2288 and add sixteen look directions. The SDK validates the asset geometry before rendering it.

JavaScript API

import { createCodexPetCompanion } from 'codex-pet-companion';

const pet = createCodexPetCompanion({
  manifestUrl: '/codex-pets/my-pet/pet.json',
  mode: 'floating',
  behaviors: { roam: true, drag: true, tuck: true, sleep: true },
  dialogue: [{
    id: 'hello',
    label: 'Hello',
    title: 'A site-specific greeting',
    body: 'The host owns the copy; the SDK owns the pet behavior.'
  }]
});

document.body.append(pet);
pet.play('waving', { loop: false, returnTo: 'idle' });
await pet.zoomies();
await pet.startRoaming(); // Idempotent: reuses this pet and keeps the natural route looping.

Public methods: play, zoomies, startRoaming, sleep, wake, tuck, and recall. startRoaming() waits for loading, promotes an inline pet to the page without creating or fetching another instance, and resolves true once its persistent route begins. Repeated calls reuse the active route. Events: codex-pet-ready, codex-pet-error, codex-pet-zoomies-start, codex-pet-zoomies-end, and codex-pet-roam-start.

React

import { CodexPetCompanion } from 'codex-pet-companion/react';

export function AppPet() {
  return <CodexPetCompanion manifestUrl="/codex-pets/my-pet/pet.json" />;
}

Existing React experiences can adopt only the 4 KB animation primitive and keep their own UI and behavior layer:

import { SpriteAnimator } from 'codex-pet-companion/animator';

const animator = new SpriteAnimator(element, {
  atlasUrl: '/codex-pets/my-pet/spritesheet.webp',
  scale: 0.5,
});
animator.setState('running-right');

CLI

Kavana does terminal zoomies while the default pet is scaffolded:

npx codex-pet-companion init .
npx codex-pet-companion validate public/codex-pets/kavana/pet.json
npx codex-pet-companion zoomies "Preparing your pet"

codex-pet-companion and codex-pet-web are aliases for the same package CLI, so either bin name works for init, validate, and the message-only zoomies command.

The installed agent skill also includes a command wrapper that keeps Kavana doing terminal zoomies while another command runs. The -- separator is required:

node .agents/skills/codex-pet-web/scripts/zoomies.mjs -- npm test

Agent skill

Install the hosted skill:

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

Then use this lean prompt:

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 the result on desktop and mobile. Show me the live integration and the checks you ran.

The skill wraps installs and deployments with Kavana's terminal zoomies and carries the framework-specific workflow.

Publishing

The inaugural version bootstraps the npm namespace interactively; subsequent releases publish from GitHub Actions with npm provenance and tokenless trusted publishing. See docs/PUBLISHING.md for the exact release and verification procedure and docs/DEPLOYING.md for the Cloudflare demo deployment.

Accessibility and CSP

• Pointer drag has click-suppression and viewport constraints.
• Arrow keys move a focused floating pet; Enter/Space uses the native button interaction.
• Tucking focuses the recall control; recalling restores focus to the pet.
• Coarse pointers keep controls visible.
• prefers-reduced-motion stops sprite and roaming animation.
• All pet surfaces remain transparent; there is no MP4/video fallback.
• The bare element loads Kavana's manifest and atlas from unpkg. For script-src 'self', connect-src 'self', and img-src 'self', run npx codex-pet-companion init ., self-host the bundle, and set manifest-url="/codex-pets/kavana/pet.json" plus atlas-url="/codex-pets/kavana/spritesheet.webp".

Ecosystem

This project focuses on a universal interactive companion and skill-driven installation. FroeMic/codex-pets-web independently provides a strong low-level renderer and framework adapters under the codex-pet-web package name. We deliberately use a distinct package name and link the projects so adopters can choose the layer they need.

Kavana originates in wildcard/kavana-codex-pet and was contributed to wildcard/caro.

License

SDK code, scripts, documentation, and metadata are MIT licensed. Bundled Kavana artwork is CC BY-NC 4.0. See LICENSE.md and THIRD_PARTY_NOTICES.md.