Docs

Install the pet

EvoPet is the pet and the desktop shell, and they install separately. You can run the pet alone, in the terminal, with no desktop app at all. From a checkout of the pet tree:

git clone <the pet tree>      # from a checkout of the pet tree
cd <the pet tree>
./hermes/install-hermes.sh --line toast --machine aurora

That one command installs the package, builds the pet into your Hermes home, copies the plugin, and selects the pet.

Enable the plugin

The plugin is how growth events reach the ledger. It is a native Hermes plugin, so it runs in process, nothing needs allowlisting, and hook callbacks only enqueue a payload — the atlas rebuild is coalesced, so a burst of tool calls triggers one rebuild rather than forty. A failed rebuild is logged and dropped, because a mascot must never break an agent turn.

The alternative is shell hooks: put the block from hermes/hooks.snippet.yaml into <HERMES_HOME>/config.yaml, replacing __REPO__ with your checkout path, then allowlist each entry with hermes hooks list. Pick one. Wiring both feeds the same ledger twice.

pets select

Selecting the pet is what makes it the active one for that profile, and it happens once per install:

hermes plugins enable tamahermes
hermes pets select tamahermes
hermes pets doctor        # should report ✓ ready

pets doctor

hermes pets doctor is the check, and it should report the pet ready. If it does not, start with the two things that go wrong most: the plugin was copied but never enabled, or the install was pointed at a home whose config.yaml still uses the legacy bare-list plugins: form.

Per-profile install

Hermes homes are profile-scoped: the pets directory is <HERMES_HOME>/pets, and HERMES_HOME is <home>/.hermes/profiles/<name> inside a named profile (unset — that is, ~/.hermes — for the default profile). So each profile owns its own pet and its own ledger, and you install once per profile you actually use.

Pointing an install at a non-live home, which is what tests and staging do, installs the pet but deliberately does not run hermes pets select, so it cannot change the config of the profile you are actually running.

install-all-profiles.sh

One command covers the default profile and every named profile on the machine. It also takes --only name1,name2 and --keep-selection (install the pet without changing which pet is active).

# every Hermes profile on this machine: the default one and ~/.hermes/profiles/*
./hermes/install-all-profiles.sh

# or one at a time
HERMES_HOME=~/.hermes/profiles/you ./hermes/install-hermes.sh
HERMES_HOME=~/.hermes                 ./hermes/install-hermes.sh

Installer flags

Float it on the desktop

The pet renders in the terminal by default. Mirroring it into the desktop shell's pet directory makes it float there too, off the same ledger:

./hermes/install-hermes.sh --petdex-activate   # close the desktop app first
./hermes/install-all-profiles.sh --petdex-activate

The mirror is a copy, not a second pet. Once the opt-in marker is recorded at <HERMES_HOME>/tamahermes/petdex-home, every growth refresh re-mirrors the sheet, so the floating pet evolves with the terminal one instead of freezing at whatever it looked like on install day.

One honest caveat: the desktop pet is machine-wide while growth ledgers are per-profile, so an unmanaged mirror shows whichever profile last changed. Installing from every profile is what keeps it current from all of them, and the combined ledger is what makes the ambiguity go away.

Environment

None of these are needed for a normal install. They exist so tests, staging and unusual layouts can point the same code somewhere else.

What is kept, and where

Only numbers are stored: XP, counters, stats and traits — never your prompts, never tool output, never a file path. The combined ledger's restriction is enforced by its own test rather than by convention.

The desktop shell

The shell is the app that floats the pet and taps every agent's hook payload, so Claude Code, Codex, opencode and Gemini CLI can feed the same creature. It is a Zig build with a pinned SDK, and today it is a local build: there is no notarized download, and a bundle built on one Mac is rejected by Gatekeeper on any other.

Because of that, the honest install path for the shell right now is to build it from the app tree on the machine that will run it. It installs as its own app, leaving the stock one in place so you can revert by quitting and reopening the other.

The shell half descends from Petdex, the desktop app shell lineage. An earlier repository published as ahrazzle/petdex is that lineage's older home; this site links the lineage as Petdex, and the older mirror is named here as prose rather than offered as a second button.

The loop

1. An agent does something; Hermes fires a hook event (prompt_sent, task_success, …).
2. The event is applied to that profile's ledger as XP plus stat changes, at the turn boundary.
3. The compiler redraws the pet's atlas and installs it. Rebuilds are coalesced, so a burst of tool calls is one redraw.
4. Every surface renders that one sheet: the terminal pet and the desktop mirror.

XP is awarded at turn boundaries, never per tool call. A turn in Codex has to be worth a turn in Hermes; per-tool accounting would inflate the pet twenty to forty times over against the ladder.

XP events

A good turn is about 18 XP — a prompt and a success — and a failing turn about 9 to 11.

The ladder

Every pet in every package climbs the same ladder, so a level means the same amount of work in every pet. It is fixed by EvoPet, cheap at the start and long at the end:

xp_for_level(L) = round(100_000 × ((L − 1) ÷ 98)²), that is CAP_XP = 100,000, MAX_LEVEL = 99, EXPONENT = 2.0.

XP is cumulative and never decreases, so a level once reached is never lost. Half the cap, 50,000 XP, lands inside level 70, and the climb from level 50 to level 99 costs 75,000 XP.

The bar fills against the level, not the form. level_progress(xp) reports the level and the position between its floor (xp_for_level(L)) and its ceiling (xp_for_level(L + 1)), so the bar fills about a hundred times in a pet's life and resets at every level-up — but the sprite changes only when a gate is crossed, because a gate is the only thing that changes the form. At level 99 the ceiling is None, the bar reports 100%, and the drawn value snaps to 5% buckets.

Evolution gates

How many evolutions a pet has, and at which levels, is the creator's choice, declared in the package's own manifest:

"evopet": { "evolutionGates": [11, 23, 32, 45] }

A gate is a level the pet reaches: when cumulative XP first equals or passes xp_for_level(gate), the pet moves to the next form. There is always one more form than gate, so one to four gates means two to five forms. The default pet declares (11, 23, 32, 45), which on the fixed ladder is:

When a declaration takes effect

1. Declare "evopet": { "evolutionGates": [11, 23, 32, 45] } in the pet.json the install will replace, or edit the installed one afterwards.
2. Install. The installer absorbs the manifest it is about to replace into the ledger (pet_compiler.sync_ledger_gates), then builds, so the new pet.json carries the ledger's gates.
3. The change takes effect on the next install, not on the next event. Nothing re-reads a manifest mid-run, and it is the ledger's own gate list — state.evolution_gates(state) — that maybe_evolve and stage_progress read.

A manifest that declares nothing leaves the ledger alone: silence is not a declaration.

What a bad gate list is told

levels.validate_gates refuses, and names the problem. These are its messages, verbatim:

• evolution gate 120 is outside 1..99
• evolution gates must strictly increase; 10 follows 30
• a pet needs at least one evolution gate
• at most 4 gates supported (5 forms); got 5

A block that is present but invalid is refused at install, and PetCompileError names the file: pet.json: evolution gates must strictly increase; 20 follows 40. A ledger with no evolutionGates key at all behaves exactly as it always has, on the default pet's gates — a growth event that raised would strand a user mid-run.

Two properties make a reached gate safe to rely on. The gate level becomes a floor in the ledger's threshold table, and XP only rises, so a pet cannot regress out of a form. And the terminal form is absent from that table, so the last form has nothing to grow into.

Forms and branches

Form names are positional and not the creator's to choose, taken from STAGE_ORDER = ("egg", "hatchling", "child", "teen", "adult"). Three gates give you egg, hatchling, child and teen — and your pet never reaches adult.

teen and adult also carry branch variants that the runtime picks from stats and traits rather than from a gate:

• teen — resilient (resilience ≥ focus + 3), restless (restlessness ≥ focus + 4), otherwise focused.
• adult, checked in order — sleepy (energy < 28, or 120+ quiet minutes), worker (≥ 4 completed runs and focus ≥ resilience), resilient (resilience ≥ focus and ≥ 2 failures), quiet (restlessness ≤ 2 and 60+ quiet minutes), otherwise calm.

Branches are sticky: once chosen they persist, and they are restored after dormancy. A branch is a record of how you worked, not a choice you make. Form ids read <line>:<branch>, for example child:root or teen:focused.

Energy and dormancy

Energy is 0–100 and is the only stat that gates behaviour: it is the awake budget.

While asleep the pet draws flat sleeping artwork — a 24×11 source union against roughly 23×24 for every other form, so it looks vertically compressed and is not — and its bar shows real progress toward the form it will wake into rather than a pinned zero.

The five trackers

Also tracked but never shown: mood (which affects nothing) and the traits focus, resilience and restlessness, which decide the branch.

What the shipped status strip draws

The top row is silent unless something needs you. Energy is the one escalation: at 45 or below the bolt and its gauge appear, amber while energy is low and red once it is critical (20 or below). The alert glyph still shows a failure or a review, and the health warning shows while health is 35 or below. The bottom row is always drawn: satiety as the bowl, growth as the centre bar, bond as the heart — which stays hidden until the pet is past "new". A direction decision for a richer HUD is still open and is not shown here.

Known limitations

These are the defects the project has recorded in its own notes and, where named, in the code. None of them is documented as working anywhere on this site.

Three further gaps are documented rather than fixed, and they matter if you are about to rely on them:

• Nothing cross-checks your gates against your spritesheet when you declare them. validate_gates checks the list's shape only, so a line that lacks a form for a stage your gates imply fails later, in the catalogue lookup, when the pet grows into it — CatalogError: no form for line ….
• A manifest's "forms" list is ignored: you cannot name your own forms.
• Gates are levels only. There is no XP amount, no branch, no condition such as three failed runs; the teen and adult branches still come from stats.

Endpoints

One service, no database, no auth provider: Node and TypeScript, deployed as a single function, with one runtime dependency (the platform's own blob client). Public and owner-only bytes are separated deliberately — an approved pet's files are served to anyone, while a pending or rejected one's are served only to its owner or an operator, and an unauthorised request gets 404 rather than 403 so a slug cannot be used to probe for hidden pets.

The index the library page reads is GET /api/manifest: public, unauthenticated, approved pets only, sorted by slug, and carrying generatedAt, total, capableTotal, assetBase and a row per pet with slug, displayName, thumbnailUrl, capable, evopet, petJsonUrl, spritesheetUrl, version and updatedAt.

Capability

Evolution capability is the evopet block, and nothing else. If a pet.json carries an object-valued evopet key the pet is capable and the parsed block is stored with the record and served in the index; otherwise it is a stock package and evopet is null. That is the desktop app's own marker, so the service refuses "evopet": "yes" rather than storing something the app would call incapable, and it asserts that its own flag agrees with the app's scanner before storing.

Declared evolutionGates are validated like levels.validate_gates: 1–4 gates, levels 1 to 99, strictly increasing. The index serves both the boolean and the block on purpose — the block is the whole truth, and the boolean is the convenience — so a client never has to re-derive the answer and never has to trust one that cannot be checked.

Package requirements

POST /api/pets/publish takes multipart/form-data only:

Validation happens before anything is stored: the manifest must parse, id must be a legal slug ([a-z0-9-], 1–64 bytes, no leading or trailing dash — it becomes a directory name under ~/.petdex/pets), displayName must fit 96 bytes, the sheet must be the documented atlas of the documented kind, and spritesheetPath must agree with the uploaded sheet.

The response is a record of what landed, not a promise:

{slug, status, url, capable, evopet, thumbnailUrl, version, replaced, notes}

Auth v1

One bearer key per user, minted by the operator CLI and stored hashed with scrypt. The secret is never written, never logged, and never returned again. Format evk1.<id>.<secret>: the id is the public lookup path, the secret is 32 random bytes. Issuing is a CLI rather than an HTTP endpoint on purpose — the first operator key would otherwise need a bootstrap secret in the environment that mints credentials, which is worse to hold than the storage token the CLI already needs.

npm run key:issue -- --email you@example.com --username you --display "owner key"
npm run key:revoke -- --id <id>

Publishing with a key:

curl -X POST "https://<host>/api/pets/publish" \
  -H "Authorization: Bearer <key>" \
  -F "pet.json=@pet.json" \
  -F "spritesheet.webp=@spritesheet.webp" \
  -F "thumbnail.png=@thumbnail.png" \
  -F "public=true"

security add-generic-password -U -s dev.petdex.desktop-native -a oauth \
  -w '{"access_token":"<key>","refresh_token":""}'
PETDEX_LIBRARY_URL=https://<host>/api/desktop/library

Publication policy

Publishing is auto-upload: with no flag a package appears in the index immediately with the status the app already understands for a listed pet, approved. The off switch is public=false, which is the only thing that produces pending — and it is the only setting in this whole system that persists a choice, written to ~/.evopet/settings.json.

pending and rejected exist because the app already has both statuses, because the off switch has to leave an unlisted package somewhere honest, and because a maintainer needs to suppress a pet without destroying it. Nothing in the default path produces them, and the rejection path is a status change, not a queue.

The catalogue is stored one object per pet, not one catalogue document. A single document would be a read-modify-write with no compare-and-swap behind it, so two concurrent publishes would silently lose one of the two pets — exactly while the library is growing. Per-pet keys make a publish a single write to a key nobody else is writing; the price is that listing is a list plus N reads, which is fine at this scale and honest about it.

Deletion and takedown

DELETE /api/pets/<slug> removes the index record and every package object. No tombstone serves anything afterwards, and the slug becomes a 404. An owner can delete their own pet; an operator key can delete any pet, optionally with a reason, and that reason is kept for maintainer deletions only, in an operator-readable audit entry.

curl -X DELETE "https://<host>/api/pets/<slug>?reason=<complaint%20ref>" \
  -H "Authorization: Bearer <operator key>"

What this site does not do

• No authenticated flow of any kind. No accounts, no OAuth, no keys, no uploads. The library page reads one public endpoint and nothing else.
• No hosted claim. The service's deploy steps live in its own repository; this site neither performs nor asserts a deployment, and it does not choose the public base URL.
• No install path that does not exist. The app reads its catalogue manifest from a compiled constant and trusts asset URLs under its own host, so petdex://<slug> installs still resolve to petdex.dev. Only the library URL is overridable. A link here would imply otherwise.

Constants

All of these live in tamahermes/levels.py. Change them there and nowhere else.

Function list

In the order you will want them:

Code map

The contract is covered by the pet's own suite: the ladder, the gates and the reports are exercised from the same formula this site renders, so a constant moved in one place and not the other is a failing test rather than a wrong page.