peon-pet - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #go #android #rust #deep-learning #linux #macos #cli #kubernetes #vue #openai #open-source

peon-pet

(★ 100)

macOS desktop pet for Peon-Ping — an orc that reacts to your Claude Code events with sprite animations.

파일 탐색기

최종 버전 다운로드 (.zip)

- - 2026-02-18-laptop-guy-session-dots-design.md
  - 2026-02-18-laptop-guy-session-dots.md
- demo.mp4
- sprite-art-guide.md
- sprite-atlas-prompt.md
- anim-state.js
- jsonl-watcher.js
- session-tracker.js
- window-position.js
- - index.js
  - package.json
- - bg-pixel.png
  - capybara-borders.png
  - capybara-dock-icon.png
  - capybara-sprite-atlas.png
  - hello-kitty-borders.png
  - hello-kitty-dock-icon.png
  - hello-kitty-sprite-atlas.png
  - laptop-guy-atlas.png
  - orc-atlas.png
  - orc-borders.png
  - orc-dock-icon.png
  - orc-sprite-atlas.png
  - peon-atlas.png
- - flash.frag
  - flash.vert
- app.js
- index.html
- gen-dock-icon.js
- gen-placeholder-atlas.js
- install-autostart.sh
- strip-atlas-bg.js
- anim-state.test.js
- assets.test.js
- jsonl-watcher.test.js
- session-tracker.test.js
- window-position.test.js
.gitignore
CHANGELOG.md
com.peonpet.app.plist
CONTRIBUTING.md
install.sh
main.js
package-lock.json
package.json
preload.js
README.md
uninstall.sh

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/PeonPing/peon-pet

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd peon-pet

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm start

개발/실행 서버를 켭니다.

npm run dev # starts with DevTools detached

개발/실행 서버를 켭니다.

npm test # runs Jest test suite (63 tests)

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# peon-pet

A macOS desktop pet for [Peon-Ping](https://peonping.com) — an orc that reacts to your Claude Code events with sprite animations. Built on Electron + Three.js.

<video src="https://github.com/user-attachments/assets/7fd9a2cb-d227-49ad-8ccc-7953ec392a2d" autoplay loop muted playsinline width="400"></video>

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

## Requirements

- macOS (Linux/Windows untested)
- Node.js 18+
- [peon-ping](https://peonping.com) installed and running

## Quick start

```bash
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 permanently (auto-start at login)

```bash
./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:

```bash
./uninstall.sh
```

## Dock controls

Right-click the dock icon:

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

## Animations

| Claude Code event | Animation |
|---|---|
| Session start / resume | Waking up (plays once) |
| Prompt submit | Typing |
| Task complete (Stop) | Celebrate |
| Permission request / context compact | Alarmed |
| Tool failure | Annoyed |

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.

## Session dots

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.

## Dependencies

- **boolean**: Replaced with a local shim (`patches/boolean-shim`) via `overrides` so the deprecated `boolean` package is not installed. The shim matches the same API (`boolean`, `isBooleanable`).
- **glob / inflight**: These come from **Jest** (and related packages). Jest 29 still uses `glob@7`, which depends on deprecated `inflight`. You may see npm deprecation warnings; they are harmless. Upgrading to `glob@10` would require Jest to use the new API (see [jestjs/jest#15173](https://github.com/jestjs/jest/issues/15173), [#15910](https://github.com/jestjs/jest/issues/15910)). Until Jest updates, the warnings can be ignored or suppressed.

## Development

```bash
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:

```bash
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`

## Sprite atlas

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

| Row | Animation |
|---|---|
| 0 | Sleeping |
| 1 | Waking |
| 2 | Typing |
| 3 | Alarmed |
| 4 | Celebrate |
| 5 | Annoyed |

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