desktop-pet
# Desktop Pet
A pixel art desktop pet (default: lobster 🦞) that roams the screen as a transparent Electron overlay.
## Quick Start
```bash
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:
```bash
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`.
```bash
# 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)
标签
skill
ai
