CARO FIELD GUIDE · COMPANION 01

Bring Kavana into Codex

Kavana is Caro’s black-and-tan Shiba Inu companion. Her name means intention in Hebrew—an apt quality for careful work in a terminal. Her package includes the complete Codex v2 animation atlas: nine task states and sixteen look directions.

A community add-on. Kavana now lives in her own standalone open-source project with an interactive field guide, and is contributed back to the Caro community. She is not an official OpenAI pet. Codex is an OpenAI product.

1. Get the official Codex desktop app

Download Codex from OpenAI’s official Codex page and sign in with your ChatGPT account. OpenAI describes the desktop app as a command center for working with coding agents across projects and worktrees. OpenAI also publishes a getting-started guide for the Codex app.

2. Download Kavana

Download Kavana’s latest release

The release archive contains one kavana/ folder with exactly two runtime files:

  • pet.json — Kavana’s identity and Codex sprite-version metadata
  • spritesheet.webp — her validated 1536×2288 animation atlas

3. Install the two files

Unzip the release, then copy its kavana/ folder into your Codex pets directory. On macOS or Linux:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/pets"
cp -R kavana "${CODEX_HOME:-$HOME/.codex}/pets/"

On Windows PowerShell:

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME '.codex' }
New-Item -ItemType Directory -Force (Join-Path $codexHome 'pets') | Out-Null
Copy-Item -Recurse -Force .\kavana (Join-Path $codexHome 'pets')

Alternatively, clone the full project and use its installer:

git clone https://github.com/wildcard/kavana-codex-pet.git
cd kavana-codex-pet
./scripts/install.sh

On Windows PowerShell, clone the project and run .\scripts\install.ps1 -Select.

Restart Codex after copying the files. Custom-pet loading is a Codex desktop behavior and can change between app releases; if Kavana is not offered in your pet controls, update Codex and use Refresh custom pets. The standalone repository also includes checksums, verification, previews, mobile-sync helpers, and public source frames.

Put any Codex pet on the web

This caro.sh companion now runs on the open-source Codex Pet Web SDK. It accepts any compatible pet.json and spritesheet, ships as an npm package and browser script, and includes Kavana as the zero-configuration default. Try the live SDK field guide or install it with npm: 

npm install codex-pet-companion

For a plain HTML site, one script and one custom element are enough:

<script src="https://unpkg.com/codex-pet-companion@0.1.0/dist/codex-pet-companion.global.js"></script>
<codex-pet-companion></codex-pet-companion>

Hatch your own Codex pet

Codex can turn a character idea or reference image into a complete companion. Start a task in the Codex app, attach any art you have permission to use, and paste this prompt: 

Use the hatch-pet skill to create a Codex pet from my idea or attached
reference art. Package and validate the full v2 animated spritesheet,
and show me the final QA preview.

A good request also tells Codex:

  • the pet’s name, personality, species or form;
  • which visual details must remain consistent;
  • the desired style, such as pixel, plush, clay, sticker, or painterly;
  • whether a prop or asymmetrical marking must face a specific direction.

The hatch workflow prepares the standard task animations, builds all sixteen directional looks, checks transparency and continuity, and packages the resulting pet.json and spritesheet.webp.

Artwork terms

Kavana may be installed and shared under the terms of her standalone project. Code and documentation are MIT licensed; artwork is CC BY-NC 4.0. See Kavana’s license and attribution before redistributing or adapting her artwork.