desktop-pet

动画像素艺术桌面宠物，作为始终位于顶部的 Electron 覆盖层在屏幕上漫游。宠物会避开光标和活动窗口，沿着屏幕边缘行走，爬上墙壁和天花板，并通过本地 HTTP API 响应代理状态更改。当用户想要桌面伴侣、屏幕伙伴、桌面吉祥物、虚拟宠物或代理活动的视觉指示器时使用。支持闲置、行走、工作、思考、睡觉、说话等状态（面对用户有气泡）。仅限 macOS。

## 概述（中文）

动画像素艺术桌面宠物，作为始终位于顶部的 Electron 覆盖层在屏幕上漫游。宠物会避开光标和活动窗口，沿着屏幕边缘行走，爬上墙壁和天花板，并通过本地 HTTP API 响应代理状态更改。当用户想要桌面伴侣、屏幕伙伴、桌面吉祥物、虚拟宠物或代理活动的视觉指示器时使用。支持闲置、行走、工作、思考、睡觉、说话等状态（面对用户有气泡）。仅限 macOS。

## 原文

# 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)