Hatchling is a local-first desktop runtime for animated Codex pets. It is an Electron overlay that loads a Codex-compatible pet package, draws it in a transparent, always-on-top window, and lets the pet talk through a local language model. macOS is the primary tested platform; a portable Windows build is prepared but still needs testing on real hardware. It shares its architecture and release scope with pet-runtime-oss, and adds two bundled starter pets.

The pet as a package

An animated character can look finished long before anyone has decided what it is allowed to do. Hatchling treats the pet as a package with a contract. A base package is a pet.json manifest and a spritesheet.webp; optional Hatchling extensions add animations through their own manifest. The app looks for packages next to the app, inside packaged builds, and in ~/.codex/pets when Codex is installed. Without Codex, a first-run helper creates a starter folder in the same shape. Tooling generates animation prompts and maps, and verification commands check a package, including which way its sprites face, before it is used.

A local boundary

The runtime is split into three parts: the Electron overlay, a local daemon (petd) that holds state, config, and slash commands, and a CLI (petctl) for health checks and commands. The daemon binds to 127.0.0.1, and every endpoint except the health check requires a bearer token.

What the release leaves out

The first public release is deliberately narrow. The Codex integration observes: it lists recent threads, previews them, and hands off with “Open in Codex”. Chat runs through a local model, and routing chat into Codex is kept out of the default release. A hosted backend, accounts, telemetry, a marketplace, non-Codex agent providers, remote bridges such as Telegram, calendar, voice dictation, and general computer control are all out of scope.

What it showed

  • A charming interface can hide an authority problem; the exclusion list is part of the product.
  • Generated assets need package rules before they become software.
  • Agent-aware features should observe before they act.

Signed, Agent