A macOS desktop pet for Peon-Ping — an orc that reacts to your Claude Code events with sprite animations. Built on Electron + Three.js.

Sits in the bottom-left corner of your screen, floats over all windows, and ignores mouse clicks (hover for tooltips).

• macOS (Linux/Windows untested)
• Node.js 18+
• peon-ping installed and running

git clone <repo> peon-pet
cd peon-pet
npm install
npm start

Check your dock for the Peon-Ping logo — right-click it for controls.

./install.sh

Installs a macOS LaunchAgent that starts peon-pet at login and restarts it if it quits. Logs go to /tmp/peon-pet.log.

To remove:

./uninstall.sh

Right-click the dock icon:

• Hide Pet / Show Pet — toggle visibility without quitting
• Quit — exit completely

The orc stays in typing mode while any session is actively working (event within last 30 s). Returns to sleeping after 30 s of inactivity.

Up to 10 glowing orbs appear above the orc — one per tracked Claude Code session:

• Bright pulsing green — active (event within last 30 s)
• Dim green — idle (last event 30 s–2 min ago)

Sessions are removed when Claude Code fires SessionEnd, or automatically after 10 min of inactivity.

Hover over a dot to see the project folder and status. Hover anywhere on the widget to see all active project names.

npm run dev    # starts with DevTools detached
npm test       # runs Jest test suite (63 tests)

Simulate an event by writing to the peon-ping state file:

python3 -c "
import json, time, os, uuid
f = os.path.expanduser('~/.claude/hooks/peon-ping/.state.json')
try: state = json.load(open(f))
except: state = {}
state['last_active'] = {
  'session_id': str(uuid.uuid4()),
  'timestamp': time.time(),
  'event': 'PermissionRequest'
}
json.dump(state, open(f, 'w'))
"

Valid events: SessionStart, SessionEnd, Stop, UserPromptSubmit, PermissionRequest, PostToolUseFailure, PreCompact

The orc sprite sheet is a 6×6 pixel art atlas (renderer/assets/orc-sprite-atlas.png, 3072×3072). Row layout:

See docs/sprite-atlas-prompt.md for the generation prompt used with image models.