wake-pets

name	wake-pets
description	Wake, validate, run, and manage already-installed Codex digital pets in the bundled native desktop overlay. Use when the user asks to spawn, wake, show, run, configure, despawn, resize, or animate one or more existing pets. Do not use to create new pet art or package new pet spritesheets.

Wake Pets

Scope

• Use only already-installed pet ids from ${CODEX_HOME:-$HOME/.codex}/pets.
• Do not create pets, generate art, repair spritesheets, or combine pets into one spritesheet.
• If a requested pet is missing or invalid, tell the user to create or repair it with $hatch-pet first.

Setup

Run shell commands from this skill directory unless a command explicitly changes directory.

Install overlay dependencies once:

scripts/setup_overlay.sh

The launcher also runs setup automatically if Electron is missing.

Manual dependency install from the runtime folder:

cd app && npm install

Update an installed skill checkout:

git pull && scripts/setup_overlay.sh

Slash Command Contract

When invoked as /wake-pets, treat the first argument as a command only when it is exactly config or stop. Otherwise, treat the full argument string as a pet list. Pet ids may be comma-separated, space-separated, or both.

• /wake-pets koji, nabi opens the overlay with koji and nabi.
• /wake-pets jack opens the overlay if needed, or adds jack to the existing overlay if it is already running.
• /wake-pets config opens or focuses the configuration window.
• /wake-pets stop closes the overlay app process.

Do not open duplicate overlay apps. Repeated pet invocations must add missing pets to the existing overlay process.

Equivalent helper commands:

scripts/run_overlay.sh koji, nabi
scripts/run_overlay.sh jack
scripts/run_overlay.sh config
scripts/run_overlay.sh stop

scripts/run_overlay.sh config koji, nabi opens config and wakes those pets.

Validate Pets

List installed pets and validation status:

scripts/list_custom_pets.py

Wake Pets

Wake one or more pets with friendly arguments:

scripts/run_overlay.sh koji, nabi

The lower-level equivalent is:

scripts/run_overlay.sh --pets koji jack nabi

The direct Electron equivalent is:

cd app && npm start -- --pets koji jack nabi

If the overlay is already running, run the same command with additional pet ids to add missing pets to the live overlay.

Direct Electron invocations can also add missing pets to the live overlay:

cd app && npm start -- --pets jack

Wake pets and open config:

scripts/run_overlay.sh --config --pets koji jack nabi

The direct Electron equivalent is:

cd app && npm start -- --config --pets koji jack nabi

Open Config

Open or focus the configuration window:

scripts/run_overlay.sh config

The direct Electron equivalent is:

cd app && npm run config

Config can wake/despawn pets, toggle movement/collisions, show or hide names, change movement speed, change idle animation speed, and resize running pets.

Stop Overlay

Use config Despawn All, despawn each pet, or stop the process:

scripts/run_overlay.sh stop

The direct process-stop equivalent is:

pkill -f 'wake-pets/app'