Skip to content

OpenPets compatibility: a shared pet format, and a reaction vocabulary worth aligning on #168

Open

Description

@omesser

Related: #112 (the pet importer and its adapters), #144 (richer AI interactions), #166 (harness integrations), #155 (the menu), #15 (the MCP tool surface).

Upstream: openpets.dev · docs · alvinunreal/openpets (MIT).

Why

OpenPets is a desktop-companion platform with our shape: animated pets in transparent always-on-top windows, gravity-and-bounce roaming, speech bubbles, agent integrations for Claude Code, OpenCode, Cursor and Pi, and a pet catalog. Deciding deliberately where we interoperate beats discovering the overlap one duplicated decision at a time.

Reading their docs turns this from speculation into two concrete facts.

1. Their pet packages are the format we already import. Per their docs, a pet package is pet.json — id, displayName, description, spritesheetPath, plus optional category, subcategory, sourceUrl, xHandle — and a spritesheet.webp grid of at least 192x208 frames. Their "Codex pets" path loads straight from ~/.codex/pets/, the same directory npx petscodex install writes and scripts/import-pet.py --format petscodex reads. Their selectable animation states are idle, review, running, waiting, waving, jumping, failed — the petdex row names. So the two projects already share an art ecosystem through petdex, and our importer very likely reads an OpenPets pet unchanged.

2. Their agent layer speaks reactions, not animations. openpets_react takes thinking, editing, testing, waiting for permission, success, error, idle; a user-configurable table maps each reaction to an animation state, a message pool supplies the speech, and the host owns rendering. Their docs state the principle outright: "agents and plugins speak in reactions, and the host owns how those look and sound" — the same split as our Behaviors-as-data with the Character owning its art.

What to decide

1. The reaction vocabulary — the highest-leverage question, and time-sensitive. Hooks already exist in the wild emitting thinking/testing/success/error at agent lifecycle points (theirs install into ~/.claude/settings.json and an OpenCode hook plugin). If our MCP tools accepted those names and mapped them onto Primitives with our own silent fallback, that existing ecosystem would drive our buddy unchanged. #144 proposes inventing working/succeeded/failed — decide this first: adopt their names, accept them as aliases, or diverge knowingly. Aligning costs nothing today and cannot be undone cheaply once Characters declare animations against our names.

2. Import: verify rather than build. The likely finding is that --format petscodex already imports an OpenPets pet, and their catalog ZIP needs only unwrapping (the importer already accepts zips). Verify with a real catalog pet, then either document it as supported or add the thin adapter the gap requires. Two small wins available while there: their optional sourceUrl and xHandle are exactly the provenance our manifest header and README attribution want, and category could seed the character catalog (#50).

3. Their reaction→animation override table as prior art. Users remapping which animation a reaction plays is a feature #155's menu and #18's settings will eventually want; their mapping/message/render separation is worth reading before we design ours.

4. Their Wayland notes for the Linux gap. They ship Linux and Wayland layer-shell docs; ai-buddy has no Linux window source at all, and layer-shell decides whether a Linux overlay is possible.

What stays different

So this does not drift into becoming a second OpenPets: our engine is a pure Rust core with real spatial life — Perches, window-riding, throwing, the Dock as a surface — where their motion is gravity-and-bounce roaming; our Director is one attached Harness session proposing Behaviors (ADR-0008), not a reaction trigger fired by hooks; we ship no plugin runtime (ADR-0003, Behaviors are declarative data); and we are Tauri rather than Electron.

Acceptance

  • A recorded decision on the reaction vocabulary — adopt, alias, or diverge — referenced from Richer AI interactions: what the model API and the Harness can carry #144 before it implements lifecycle Behaviors.
  • A real OpenPets catalog pet imported and running, or a recorded reason it cannot be, with the docs updated either way.
  • Provenance fields (sourceUrl, xHandle) used by the importer if they are there to use.
  • No code vendored; their repo is MIT and this issue is about interoperating.

Activity

  1. added
    enhancementNew feature or request
    ready-for-agentFully specified, ready for an AFK agent
    needs-triageMaintainer needs to evaluate this issue
    and removed
    ready-for-agentFully specified, ready for an AFK agent
    on Sep 1, 2026
  2. moved this from Todo to Ice Box in Fidgeton Sep 3, 2026
  3. modified the milestones: V2, V1 on Sep 6, 2026
  4. added
    p2Eventually: real, but nothing waits on it
    on Sep 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-triageMaintainer needs to evaluate this issuep2Eventually: real, but nothing waits on it

    Projects

    • Status
      Ice Box

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions