WorkBuddy Pet Factory

Problem

Desktop pets are often built as one hardcoded character: the animation, path, and launch logic are all wired to a single sprite. workbuddy-pet treats a pet as an installable asset. From a character image, a codex.pet link, a spritesheet, or an already downloaded codex pet, it creates a manageable instance under ~/.workbuddy/pets/<id>/, with pet.json describing layout, states, and runtime behavior.

How It Works

• Install sources: supports image, URL, codex, and spritesheet paths; image input needs a normalized spritesheet before runtime metadata is finalized.
• Spritesheet contract: default sheet is 1536×1872, arranged as 9 rows × 8 columns with 192×208 frames; non-standard sheets can override rows/frame layout in pet.json.
• Status linkage: every pollIntervalMs (default 2000ms), it reads ~/.workbuddy/workbuddy.db and maps statuses such as working, Pending, Completed, and Failed to short running, waiting, jumping, or review animations, then returns to idle.
• Process policy: on macOS it uses a frameless, always-on-top window at NSStatusWindowLevel, with accessory behavior and no focus stealing; only one active pet is kept at a time, so starting or switching stops other pets.
• Interaction: besides command-line control, a right-click menu can list installed pets, test animations, hide for 30 seconds, or exit.

Boundaries

This is a pet runtime and factory, not a general GUI automation framework. Spritesheets must follow the expected layout or provide a layout override; image sources depend on a sprite-normalization step; if the target environment lacks the macOS focus APIs or pyobjc, top-most and no-focus behavior may be unavailable.