---
title: "Kavana: your Codex pet"
description: "Meet Kavana, install her as a community pet in the Codex desktop app, or use Codex to hatch an animated companion of your own."
url: "https://caro.sh/docs/kavana"
markdown_url: "https://caro.sh/docs/kavana.md"
lang: "en"
type: "website"
image: "https://caro.sh/og/docs/kavana.png"
---

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](https://github.com/wildcard/kavana-codex-pet) with an [interactive field guide](https://kavana.pet/), 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](https://openai.com/codex/) 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](https://openai.com/academy/codex-how-to-start/).

## 2. Download Kavana

[Download Kavana’s latest release](https://github.com/wildcard/kavana-codex-pet/releases/latest)

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](https://github.com/wildcard/codex-pet-companion). 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](https://codexpet.dev/) 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](https://github.com/wildcard/kavana-codex-pet/blob/main/LICENSE.md) and [attribution](https://github.com/wildcard/kavana-codex-pet/blob/main/ATTRIBUTION.md) before redistributing or adapting her artwork.