Desktop Pet

A pixel art desktop pet (default: lobster 🦞) that roams the screen as a transparent Electron overlay.

Quick Start

cd <skill-dir>/assets/app
npm install
npx electron .

The pet starts at the bottom center of the screen and begins roaming.

HTTP API

Local API on port 18891 (127.0.0.1 only):

GET /state - returns {"state":"idle","statusText":""}
POST /state - set state: {"state":"talking","bubble":"hello!"}

States

State	Behavior
`idle`	Gentle bob, occasional claw snap
`walking`	Moves along current surface
`climbing`	Transitions between floor/walls/ceiling
`fleeing`	Running from cursor or active window
`working`	Sits at tiny laptop with sparkle particles
`thinking`	Slow sway, thought dots appear
`sleeping`	Eyes closed, zzz bubbles float up
`talking`	Faces user, shows speech bubble, auto-returns to idle
`snapping`	Claw snap animation

Agent Integration

Hit the API at the start of responses to make the pet face the user:

curl -s -X POST http://127.0.0.1:18891/state 
  -H 'Content-Type: application/json' 
  -d '{"state":"talking","bubble":"working on it..."}'

Set to working during long operations, thinking while reasoning.

The talking state auto-returns to idle after the bubble duration expires.

Auto-Launch (macOS)

Create a LaunchAgent for auto-start on login. Use label ai.openclaw.desktop-pet.

# Install as LaunchAgent
cat > ~/Library/LaunchAgents/ai.openclaw.desktop-pet.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
  <key>Label</key><string>ai.openclaw.desktop-pet</string>
  <key>ProgramArguments</key><array>
    <string>APP_PATH/node_modules/.bin/electron</string>
    <string>APP_PATH</string>
  </array>
  <key>WorkingDirectory</key><string>APP_PATH</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/desktop-pet.log</string>
  <key>StandardErrorPath</key><string>/tmp/desktop-pet.log</string>
  <key>EnvironmentVariables</key><dict>
    <key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
  </dict>
</dict></plist>
EOF

Replace APP_PATH with the absolute path to the app directory.

Customization

The pet is drawn programmatically via Canvas pixel art in index.html. To change the creature:

Edit lobsterBase() and lobsterFront() functions with new pixel layouts
Colors are defined as constants at the top of the script block
Each pixel is {x, y, w, h, color} at 3x scale

Features

Transparent overlay, always-on-top, click-through (except on the pet itself)
Roams full desktop: floor, walls, ceiling
Avoids cursor (250px radius) and frontmost window
Right-click context menu for manual state control
Speech bubbles with auto-sizing duration
Pixel art drawn via Canvas (no external images needed)

mu-pet

Installation