clawchat-pet

A Hermes Agent plugin that turns agent activity into one persistent pet growth journey and projects it through selectable gameplay scenes for ClawChat.

Features

• Starts and serves the local pet API and bundled web UI
• Ensures one fixed ClawPet Liveware app is logged in, created, bound, and registered
• Converts Hermes activity hooks into shared growth progress and structured event facts
• Aggregates parallel tools, approvals, turns, and subagents into one activity display
• Uses the current Petdex entry as pet identity while sharing progress across pets and scenes
• Stores an optional text-only personality independently for each Petdex slug
• Ships xianxia and star-voyage scene adapters over the same settlement rules
• Supports pets, skins, stages, capabilities, assets, strategies, and idle progression
• Registers the bundled clawchat-pet skill with Hermes

Installation

Install and enable the plugin directly from GitHub, then restart the Gateway so the plugin and its startup hook are loaded. No separate Python dependency installation is required for a directory plugin install:

hermes plugins install XMethues/clawpet --enable
hermes gateway restart

Runtime

When Hermes loads the plugin, it registers the activity hooks and skill, then:

1. Materializes the bundled clawchat-pet-startup Gateway hook under the active Hermes home
2. Activates that hook for the current process without binding a runtime port

When the Gateway emits gateway:startup, that hook ensures that:

1. The pet service is running on 127.0.0.1:54321
2. The current pet asset is cached locally, downloading it when missing
3. A Liveware app named ClawPet exists and is bound to the pet service
4. The app is registered in ClawChat and the Liveware tunnel agent is running

Liveware agent startup and publication repair run in one background worker so pet asset, Liveware, or ClawChat failures do not block the Gateway. The worker starts only for the Gateway, after messaging platforms connect; ordinary Hermes CLI plugin discovery does not bind the pet service port or start Liveware. A valid saved Liveware login and an existing ClawPet app are reused. The binding is refreshed on every Gateway startup because the Liveware CLI does not expose a binding query; app creation and ClawChat registration only run when missing or stale. If an older Liveware app identity left a same-name ClawChat registration behind, the worker removes only that stale ClawPet registration.

Runtime state is stored outside this repository under ~/.hermes/clawchat-pet/. One authoritative runtime owns save.json, its lock, and atomic commits. Shared growth, current pet, per-pet personalities, current scene/skin, and per-skin visual overrides live in that one save. Petdex sprite/index files are cache, not product state. Transient activity is memory-only and returns to idle whenever the Hermes plugin process restarts. Hermes hooks call the runtime directly in-process.

The runtime accepts only the current save.json schema. It does not reset, migrate, or convert older formats; remove a noncurrent save manually before starting this version.

Gameplay scenes

The display-only frontend reads one projected presentation. The bundled skill performs changes through the catalog and command interface:

GET  /presentation
GET  /catalog
POST /command   {"type":"select_scene","scene_id":"star-voyage"}

xianxia is the default scene and star-voyage is the second built-in adapter. A scene owns multiple compatible skins and one default skin. A skin changes only visual tokens; user overrides are stored against that skin. Selecting a scene also selects its default skin.

To add a built-in scene, define another SceneDefinition in clawchat_pet/gameplay.py, register it in GameplayScenes, and add at least one matching skin in clawchat_pet/skins.py. A scene supplies stage, meter, strategy, activity, voice, capability, asset, and chronicle labels for fixed shared-growth slots. It cannot settle progress. PetPresentation validates the scene/skin relationship and produces the single read model.

Python environment

Python dependencies are managed with uv. The project targets the same Python 3.11 minimum as Hermes Agent. The runtime works without third-party Python packages: it caches Petdex WebP sprites directly and uses safe static activity frames. Pillow is an optional development dependency that enables exact non-empty animation-frame scanning and PNG conversion.

uv sync --locked
uv sync --locked --group sprite-analysis  # optional Pillow enhancement

Frontend

The complete Vite + React + TypeScript project is in frontend/. The generated production bundle is committed under clawchat_pet/web/ so the plugin works immediately after installation.

cd frontend
npm ci
npm run dev      # development server with API proxy
npm run build    # rebuilds ../clawchat_pet/web/

Tests

uv run --locked python -m unittest discover -s tests -v