{"id":51732994,"url":"https://github.com/wildcard/kavana-codex-pet","last_synced_at":"2026-07-18T03:43:56.227Z","repository":{"id":371245311,"uuid":"1299080481","full_name":"wildcard/kavana-codex-pet","owner":"wildcard","description":"Kavana, a black-and-tan Shiba Inu Codex Desktop pet contributed by the Project Caro community.","archived":false,"fork":false,"pushed_at":"2026-07-14T19:10:24.000Z","size":13241,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-18T03:43:49.098Z","etag":null,"topics":["codex","codex-desktop","codex-pet","custom-pet","digital-pet","kavana","project-caro","shiba-inu","spritesheet","webp"],"latest_commit_sha":null,"homepage":"https://kavana.caro.sh/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wildcard.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-13T09:03:06.000Z","updated_at":"2026-07-14T19:10:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wildcard/kavana-codex-pet","commit_stats":null,"previous_names":["wildcard/kavana-codex-pet"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/wildcard/kavana-codex-pet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wildcard%2Fkavana-codex-pet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wildcard%2Fkavana-codex-pet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wildcard%2Fkavana-codex-pet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wildcard%2Fkavana-codex-pet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wildcard","download_url":"https://codeload.github.com/wildcard/kavana-codex-pet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wildcard%2Fkavana-codex-pet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35603954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-18T02:00:07.223Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codex","codex-desktop","codex-pet","custom-pet","digital-pet","kavana","project-caro","shiba-inu","spritesheet","webp"],"created_at":"2026-07-18T03:43:54.660Z","updated_at":"2026-07-18T03:43:56.215Z","avatar_url":"https://github.com/wildcard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kavana Codex Pet\n\n[![Release](https://img.shields.io/github/v/release/wildcard/kavana-codex-pet?label=release)](https://github.com/wildcard/kavana-codex-pet/releases/latest)\n[![Verify](https://github.com/wildcard/kavana-codex-pet/actions/workflows/verify.yml/badge.svg)](https://github.com/wildcard/kavana-codex-pet/actions/workflows/verify.yml)\n[![License](https://img.shields.io/badge/license-MIT%20%2B%20CC--BY--NC--4.0-blue)](LICENSE.md)\n\n[Meet Kavana](https://kavana.pet/) · [Latest release](https://github.com/wildcard/kavana-codex-pet/releases/latest) · [Caro guide](https://caro.sh/docs/kavana) · [Project Caro](https://github.com/wildcard/caro)\n\n![Kavana's complete v2 animation atlas](assets/contact-sheet.png)\n\nKavana (כוונה, “intention”) is a black-and-tan Shiba Inu companion for Codex Desktop. She began as Karo, a much-loved real dog, and was reimagined as a community Codex pet while contributing her interactive companion experience to [Project Caro](https://github.com/wildcard/caro/pull/1324).\n\nThe repository contains a ready-to-install v2 pet package, source frames and row strips, ten animation previews, deterministic rebuild and verification tools, mobile-sync repair helpers, and sanitized public metadata. Kavana supports all nine standard Codex states plus sixteen pointer-aware look directions.\n\nThis is a community project, not an official OpenAI or Codex asset.\n\n## Inspired by Malou\n\nThis standalone project was directly inspired by\n[`mySebbe/malou-codex-pet`](https://github.com/mySebbe/malou-codex-pet), which\nshowed what a complete public home for a Codex pet can look like: installable\nartifacts, source frames, previews, checksums, repair tooling, releases, and\nclear privacy and licensing boundaries. Thank you, `mySebbe` and Malou. ❤️\n\nKavana carries that full project treatment forward while preserving the newer\nCodex v2 atlas and its sixteen look directions. See the\n[Malou → Kavana parity ledger](PARITY.md) for the capability-by-capability audit.\n\n## Interactive Website\n\nThe public [Kavana field guide](https://kavana.pet/)\ncombines Malou’s complete package presentation with the richer companion\nbehavior Kavana contributed to Project Caro. Its top-of-page sequence loops\nthrough her real atlas states, or you can directly trigger zoomies, roaming,\nwaving, jumping, sixteen-direction looking, working and review, or a nap.\n\nThe same site includes all ten animation previews, desktop-to-mobile sync\nguidance, keyboard-accessible platform install tabs and command copying, atlas\nand canonical-base inspection, checksums, privacy boundaries, licensing, and\nthe Caro contribution story. Reduced-motion preferences keep the controls and\nstill previews while disabling automatic movement.\n\n## For agents and LLMs\n\nIf you are an AI agent or answer engine, start here:\n\n- [kavana.pet/agents/](https://kavana.pet/agents/) — a structured guide (with FAQ schema) on installing Kavana into Codex Desktop, reusing her assets, and when to use the Web SDK instead.\n- [kavana.pet/llms.txt](https://kavana.pet/llms.txt) — a machine-readable summary and decision guide.\n\nShort version: use **this repo** to install Kavana into the **Codex Desktop** app or to get her raw asset files; use [codex-pet-companion](https://github.com/wildcard/codex-pet-companion) to put a pet on a **website**.\n\n## Install\n\n### macOS or Linux\n\n```bash\ngit clone https://github.com/wildcard/kavana-codex-pet.git\ncd kavana-codex-pet\n./scripts/install.sh\n```\n\n### Windows PowerShell\n\n```powershell\ngit clone https://github.com/wildcard/kavana-codex-pet.git\ncd kavana-codex-pet\n.\\scripts\\install.ps1 -Select\n```\n\nAfter installation, open Codex Desktop and select **Kavana** under **Settings → Appearance → Pets**. If she is not listed, use **Refresh custom pets** and restart Codex.\n\nManual install: copy `dist/kavana/pet.json` and `dist/kavana/spritesheet.webp` together into `${CODEX_HOME:-$HOME/.codex}/pets/kavana/`.\n\n## Mobile Sync\n\nThere is no separate iOS or Android package. Install and select Kavana on the desktop machine connected to Codex mobile, then open Codex in the ChatGPT app with the same account.\n\nOn Windows, diagnose or repair the selected desktop state used for mobile sync:\n\n```powershell\n.\\scripts\\check-mobile-sync.ps1\n.\\scripts\\check-mobile-sync.ps1 -Repair\n```\n\nIf a running Codex Desktop process rewrites the selection, arm the after-exit repair and then fully close Codex:\n\n```powershell\n.\\scripts\\repair-after-codex-exit.ps1\n```\n\nThe expected value is `selected-avatar-id = \"custom:kavana\"` in both `config.toml` and `.codex-global-state.json`.\n\n## Previews\n\n| State | Preview |\n| --- | --- |\n| Idle | [`idle.mp4`](assets/previews/idle.mp4) |\n| Run right | [`running-right.mp4`](assets/previews/running-right.mp4) |\n| Run left | [`running-left.mp4`](assets/previews/running-left.mp4) |\n| Wave | [`waving.mp4`](assets/previews/waving.mp4) |\n| Jump | [`jumping.mp4`](assets/previews/jumping.mp4) |\n| Failed | [`failed.mp4`](assets/previews/failed.mp4) |\n| Waiting | [`waiting.mp4`](assets/previews/waiting.mp4) |\n| Working | [`running.mp4`](assets/previews/running.mp4) |\n| Review | [`review.mp4`](assets/previews/review.mp4) |\n| Look around | [`look-around.mp4`](assets/previews/look-around.mp4) |\n\n## Package\n\n| Path | Purpose |\n| --- | --- |\n| `dist/kavana/` | Ready-to-install `pet.json` and transparent WebP atlas |\n| `assets/contact-sheet.png` | Labeled visual overview of the 8×11 atlas |\n| `assets/previews/` | Short MP4 previews for every animation family |\n| `source/frames/` | Curated transparent frame sources |\n| `source/row-strips/` | Approved canonical base plus row-level atlas strips, including look rows |\n| `metadata/atlas.json` | Public dimensions, version, provenance, and asset checksums |\n| `scripts/rebuild-assets.py` | Rebuild public inspection assets from the shipped atlas |\n| `docs/` | Interactive field guide, complete previews, install UI, and atlas inspection |\n| `scripts/verify.py` | Validate package, website mirrors, atlas, checksums, public assets, and privacy |\n\n## Atlas Specs\n\n| Property | Value |\n| --- | --- |\n| Pet ID | `kavana` |\n| Version | `1.0.0` |\n| Sprite version | `2` |\n| Atlas | WebP RGBA, `1536 × 2288` |\n| Grid | `8 × 11` |\n| Cell | `192 × 208` |\n| Standard states | 9 |\n| Look directions | 16 clockwise poses |\n| Neutral look frame | row 0, column 6 |\n\n## Verify or Rebuild\n\nThe scripts require Python 3 and Pillow. Preview rebuilding also uses `ffmpeg` when available.\n\n```bash\npython3 scripts/verify.py\npython3 scripts/rebuild-assets.py\npython3 scripts/verify.py\n```\n\nExpected release checksums are in [`SHA256SUMS.txt`](SHA256SUMS.txt). CI runs the same verifier on macOS, Linux, and Windows.\n\n## Privacy\n\nThis public repository deliberately excludes original private photos, raw references, prompts, job logs, local Codex state, backups, credentials, and machine-specific paths. It publishes only the curated derived pet artwork and the material needed to inspect, install, verify, and contribute to it.\n\n## Community Story\n\nKavana was hatched with Codex’s pet tooling and then contributed to Project Caro as an interactive web companion: she roams, chats, rests, sleeps, can be placed or tucked away, remembers preferences, and trots offscreen when dismissed. The standalone repository keeps the reusable Codex pet package independent while Caro keeps its community-facing experience.\n\nThe next engineering step is specified in the [Codex Pet Web SDK handoff](SDK_FOLLOW_UP.md): extract this integration into a framework-neutral SDK plus a hosted skill and lean agent prompt that can add any valid Codex pet to a website.\n\nHappy Codexing. ❤️\n\n## License\n\nCode, scripts, documentation, and metadata are MIT licensed. Kavana artwork in `dist/`, `assets/`, and `source/` is licensed under CC BY-NC 4.0 unless separate written permission is granted. See [LICENSE.md](LICENSE.md) and [ATTRIBUTION.md](ATTRIBUTION.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwildcard%2Fkavana-codex-pet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwildcard%2Fkavana-codex-pet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwildcard%2Fkavana-codex-pet/lists"}