{"_id":"@drakulavich/peon-pet","_rev":"3-f4e5202934e57491258a3b24e7522ea6","name":"@drakulavich/peon-pet","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@drakulavich/peon-pet","version":"0.1.0","keywords":["claude-code","desktop-pet","peon-ping","macos","bun","appkit","orc"],"author":{"url":"drakulavich","name":"Anton Yakutovich"},"license":"MIT","_id":"@drakulavich/peon-pet@0.1.0","maintainers":[{"name":"drakulavich","email":"drakulavich@gmail.com"}],"homepage":"https://github.com/drakulavich/peon-pet#readme","bugs":{"url":"https://github.com/drakulavich/peon-pet/issues"},"os":["darwin"],"bin":{"peon-pet":"bin/peon-pet"},"cpu":["arm64"],"dist":{"shasum":"7cf2578cc52518ad18220e53fabc3d9d949e4143","tarball":"https://registry.npmjs.org/@drakulavich/peon-pet/-/peon-pet-0.1.0.tgz","fileCount":31,"integrity":"sha512-SsLfdNRwcQBWcEkrrsAwq214tLXjttrMrhkf+bI1IHteu59q0aKnLQmaV8ZBQ7/AMAogG4Zika0uTfu/aBssVg==","signatures":[{"sig":"MEYCIQC88afHEoJsIUrJZtxP3oibKCjiN265cqePo3dbgHreOwIhAI71vhtnJiV9zfGg3m3cAiDCHACO1kqPXpKSgcIWuwV8","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6178337},"type":"module","module":"src/main.ts","engines":{"bun":">=1.3.0"},"gitHead":"d78c3326501caac042fd9e3e6cee685b94a41e54","scripts":{"dev":"bun run build:native && bun run src/main.ts --dev","demo":"bun run src/demo-orc.ts","test":"bun test","spike":"bun run src/spike.ts","start":"bun run build:native && bun run src/main.ts","prepack":"bun run build:native && bun run vendor:three","test:watch":"bun test --watch","build:native":"clang -framework Cocoa -framework WebKit -dynamiclib -fobjc-arc -o native/libpeonshell.dylib native/peonshell.m","vendor:three":"bun run scripts/vendor-three.ts"},"_npmUser":{"name":"drakulavich","email":"drakulavich@gmail.com"},"repository":{"url":"git+https://github.com/drakulavich/peon-pet.git","type":"git"},"_npmVersion":"11.12.1","description":"A macOS desktop pet for Peon-Ping — an orc that reacts to your Claude Code events. Native Bun + AppKit (no Electron).","directories":{},"_nodeVersion":"26.0.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"three":"^0.183.0","canvas":"^3.2.1","@types/bun":"^1.3.14"},"_npmOperationalInternal":{"tmp":"tmp/peon-pet_0.1.0_1781002514970_0.5402387597454832","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@drakulavich/peon-pet","version":"0.1.1","keywords":["claude-code","desktop-pet","peon-ping","macos","bun","appkit","orc"],"author":{"url":"drakulavich","name":"Anton Yakutovich"},"license":"MIT","_id":"@drakulavich/peon-pet@0.1.1","maintainers":[{"name":"drakulavich","email":"drakulavich@gmail.com"}],"homepage":"https://github.com/drakulavich/peon-pet#readme","bugs":{"url":"https://github.com/drakulavich/peon-pet/issues"},"os":["darwin"],"bin":{"peon-pet":"bin/peon-pet"},"cpu":["arm64","x64"],"dist":{"shasum":"4642cf6485a5f223efb8aa6c1e98c55c74b06b53","tarball":"https://registry.npmjs.org/@drakulavich/peon-pet/-/peon-pet-0.1.1.tgz","fileCount":31,"integrity":"sha512-PpWFJM7frG4hT6JkC3Iev47LO5NuLQblaOJXBSY0RzsSuzUWZb+CirgazI/aFgZshRh5Q3z2wztvGk4D4w97/g==","signatures":[{"sig":"MEYCIQCkEWwhVed9N9SNMPiph9oVRZfs/q4GjDNDygzLloTR1gIhAKvhOEw+7tFdxXSr5ATrEU+Hs9RoM9LM5zxPp8bYV49e","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@drakulavich%2fpeon-pet@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":6243928},"type":"module","module":"src/main.ts","engines":{"bun":">=1.3.0"},"gitHead":"4fa9294b9ec68becc37da8ce88f98c91901707c0","scripts":{"dev":"bun run build:native && bun run src/main.ts --dev","demo":"bun run src/demo-orc.ts","test":"bun test","spike":"bun run src/spike.ts","start":"bun run build:native && bun run src/main.ts","prepack":"bun run build:native && bun run vendor:three","test:watch":"bun test --watch","build:native":"clang -arch arm64 -arch x86_64 -framework Cocoa -framework WebKit -dynamiclib -fobjc-arc -o native/libpeonshell.dylib native/peonshell.m","vendor:three":"bun run scripts/vendor-three.ts"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:98d57203-a5a9-4d20-9305-477a56c5abc4"}},"repository":{"url":"git+https://github.com/drakulavich/peon-pet.git","type":"git"},"_npmVersion":"11.16.0","description":"A macOS desktop pet for Peon-Ping — an orc that reacts to your Claude Code events. Native Bun + AppKit (no Electron).","directories":{},"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"three":"^0.183.0","canvas":"^3.2.1","@types/bun":"^1.3.14"},"_npmOperationalInternal":{"tmp":"tmp/peon-pet_0.1.1_1781177024599_0.8568420765279434","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@drakulavich/peon-pet","version":"0.1.2","description":"A macOS desktop pet for Peon-Ping — an orc that reacts to your Claude Code events. Native Bun + AppKit (no Electron).","type":"module","module":"src/main.ts","bin":{"peon-pet":"bin/peon-pet"},"license":"MIT","author":{"name":"Anton Yakutovich","url":"drakulavich"},"homepage":"https://github.com/drakulavich/peon-pet#readme","repository":{"type":"git","url":"git+https://github.com/drakulavich/peon-pet.git"},"bugs":{"url":"https://github.com/drakulavich/peon-pet/issues"},"keywords":["claude-code","desktop-pet","peon-ping","macos","bun","appkit","orc"],"os":["darwin"],"cpu":["arm64","x64"],"engines":{"bun":">=1.3.0"},"publishConfig":{"access":"public"},"scripts":{"start":"bun run build:native && bun run src/main.ts","dev":"bun run build:native && bun run src/main.ts --dev","test":"bun test","test:watch":"bun test --watch","build:native":"clang -arch arm64 -arch x86_64 -framework Cocoa -framework WebKit -dynamiclib -fobjc-arc -o native/libpeonshell.dylib native/peonshell.m","vendor:three":"bun run scripts/vendor-three.ts","prepack":"bun run build:native && bun run vendor:three","spike":"bun run src/spike.ts","demo":"bun run src/demo-orc.ts"},"devDependencies":{"@types/bun":"^1.3.14","canvas":"^3.2.1","three":"^0.183.0"},"gitHead":"48c94e3533e31a31d5108a609ec55f0cef2d6777","_id":"@drakulavich/peon-pet@0.1.2","_nodeVersion":"22.22.3","_npmVersion":"11.17.0","dist":{"integrity":"sha512-ybjxJ9Pb3CiR13reVCFIKcFuO94VZVDlbj8FsudyVoc4hM2NWk54RiTjtPLpD2JAG+gzQgVJP7/9yUxTxeqdFQ==","shasum":"2e3beb2648e1185a52ab34839ea5adf76e0280b9","tarball":"https://registry.npmjs.org/@drakulavich/peon-pet/-/peon-pet-0.1.2.tgz","fileCount":31,"unpackedSize":6241388,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@drakulavich%2fpeon-pet@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAIDXT4p9uuuFGFc1Gy5SgmQ1OA4/E3/DCdcAQkxMSHEAiBxnLUWRfQAhoosEDNxmMclh0njUDR2MO6Mro62PZtXtw=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:98d57203-a5a9-4d20-9305-477a56c5abc4"}},"directories":{},"maintainers":[{"name":"drakulavich","email":"drakulavich@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/peon-pet_0.1.2_1781252764506_0.08372410922218898"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-09T10:55:14.852Z","modified":"2026-06-12T08:26:04.990Z","0.1.0":"2026-06-09T10:55:15.188Z","0.1.1":"2026-06-11T11:23:44.856Z","0.1.2":"2026-06-12T08:26:04.720Z"},"bugs":{"url":"https://github.com/drakulavich/peon-pet/issues"},"author":{"name":"Anton Yakutovich","url":"drakulavich"},"license":"MIT","homepage":"https://github.com/drakulavich/peon-pet#readme","keywords":["claude-code","desktop-pet","peon-ping","macos","bun","appkit","orc"],"repository":{"type":"git","url":"git+https://github.com/drakulavich/peon-pet.git"},"description":"A macOS desktop pet for Peon-Ping — an orc that reacts to your Claude Code events. Native Bun + AppKit (no Electron).","maintainers":[{"name":"drakulavich","email":"drakulavich@gmail.com"}],"readme":"# peon-pet\n\nA macOS desktop pet for [Peon-Ping](https://peonping.com) — an orc that reacts to your Claude Code events with sprite animations. Built on **Bun + AppKit + Three.js** (no Electron — a native `NSPanel` driven via `bun:ffi`, rendering the Three.js scene in system WebKit).\n\n<video src=\"https://github.com/user-attachments/assets/7fd9a2cb-d227-49ad-8ccc-7953ec392a2d\" autoplay loop muted playsinline width=\"400\"></video>\n\nSits in the bottom-left corner of your screen and floats over all windows. Clicks pass through to whatever's underneath — except when you hover the orc itself, where it captures the mouse so you can read tooltips and drag it around.\n\n## Requirements\n\n- macOS (the shell is AppKit-native; Linux/Windows are non-goals)\n- [Bun](https://bun.sh) 1.3+\n- Xcode Command Line Tools (`clang`, to build the native shim) — `xcode-select --install`\n- [peon-ping](https://peonping.com) installed and running\n\n## Install (npm)\n\n```bash\nbunx @drakulavich/peon-pet               # run it once\n# or install globally:\nbun add -g @drakulavich/peon-pet && peon-pet\n```\n\nRequires **macOS (Apple Silicon or Intel)**, **[Bun](https://bun.sh)**, and **peon-ping** running.\nA prebuilt universal (arm64 + x86_64) native shim ships in the package — no Xcode needed. Pass `--character <name>`\nor `--corner <corner>` as below.\n\n## Run from source (development)\n\n```bash\ngit clone https://github.com/drakulavich/peon-pet\ncd peon-pet\nbun install\nbun run start      # builds the native shim, then launches the pet\n```\n\n`bun run start` compiles `native/libpeonshell.dylib` (a tiny AppKit shim) and runs\n`src/main.ts`. Check your dock for the Peon-Ping logo.\n\n## Install permanently (auto-start at login)\n\n```bash\n./install.sh\n```\n\nInstalls a macOS LaunchAgent that starts peon-pet at login and restarts it if it quits. Logs go to `/tmp/peon-pet.log`.\n\nTo remove:\n\n```bash\n./uninstall.sh\n```\n\n## Controls\n\nRight-click the **Peon-Ping dock icon** for a menu:\n\n- **Hide Pet** / **Show Pet** — toggle visibility (orc + any sub-agent mini-pets) without quitting\n- **Quit** — exit completely\n\nYou can also **drag** the orc with the mouse to move it, and quit with `Ctrl-C` in the\nforeground (or `./uninstall.sh` to remove the LaunchAgent). Only one instance runs at\na time — launching a second just exits.\n\n## Characters\n\nThe bundled skin is **orc**. You can add your own and select it in config or with a\nCLI flag:\n\n```bash\nbun run build:native                  # once\nbun src/main.ts --character my-skin   # or --corner top-right\n```\n\nConfig lives at `~/Library/Application Support/peon-pet/peon-pet-config.json` (the\nlegacy Electron `Peon Pet` dir is reused automatically if you're upgrading):\n\n```json\n{ \"character\": \"my-skin\", \"corner\": \"bottom-right\" }\n```\n\n**Custom skins:** drop your own PNGs in\n`~/Library/Application Support/peon-pet/characters/<name>/` —\n`sprite-atlas.png`, `borders.png`, `bg.png`, `dock-icon.png`. Any asset you don't\nprovide falls back to the bundled orc. Precedence for the active character is\n`--character` > config > `orc`.\n\n## Animations\n\n| Claude Code event | Animation |\n|---|---|\n| Session start / resume | Waking up (plays once) |\n| Prompt submit | Typing |\n| Task complete (Stop) | Celebrate |\n| Permission request / context compact | Alarmed |\n| Tool failure | Annoyed |\n\nThe orc stays in typing mode while any session is actively working (event within last 30 s). Returns to sleeping after 30 s of inactivity.\n\n## Session dots\n\nUp to 10 glowing orbs appear above the orc — one per tracked Claude Code session:\n\n- **Bright pulsing green** — active (event within last 30 s)\n- **Dim green** — idle (last event 30 s–2 min ago)\n\nSessions are dropped automatically after 10 min of inactivity (the JSONL transcript\nmodel has no explicit \"session end\" — they decay).\n\nHover over a dot to see the project folder and status. Hover anywhere on the widget to see all active project names.\n\n## Sub-agents\n\nWhen a session spawns sub-agents, a mini-orc (up to 5) pops up stacked above the main\npet for each active sub-agent and disappears when it finishes. The parent session is\nkept \"awake\" while its sub-agents run, so the orc doesn't fall asleep during long\nsub-agent tasks.\n\n## Architecture\n\n```\nsrc/main.ts          composition root: window + watcher + session tracker\nsrc/shell/\n  types.ts           NativeShell boundary (interface)\n  appkit.ts          real shell — bun:ffi → native/libpeonshell.dylib\n  fake.ts            in-memory shell for headless tests\nsrc/app/             ported logic (session tracker, jsonl watcher, anim, …)\nnative/peonshell.m   thin AppKit/WebKit C shim (NSPanel + WKWebView +\n                     peon-asset:// scheme handler); built to libpeonshell.dylib\nrenderer/            unchanged Three.js renderer, loaded over peon-asset://\n```\n\nThe only file that touches `bun:ffi` is `src/shell/appkit.ts`. Everything above the\n`NativeShell` boundary is tested against `FakeShell`, so the suite runs headlessly.\n\n## Development\n\n```bash\nbun run dev    # builds the shim, runs with native diagnostics (--dev)\nbun test       # 182 tests, headless (no window opened)\nbun run build:native   # rebuild native/libpeonshell.dylib after editing the shim\n```\n\nSpecs of record live under `openspec/specs/` (capabilities), with shipped changes\narchived in `openspec/changes/archive/`.\n\nThe pet reacts to Claude Code automatically: just use Claude Code and watch the orc\nwake / type / celebrate. With `bun run dev` the terminal echoes each reaction, e.g.\n`→ orc: typing (UserPromptSubmit)`.\n\nValid events: `SessionStart`, `Stop`, `UserPromptSubmit`, `PermissionRequest`, `PostToolUseFailure`, `PreCompact`\n\n## Sprite atlas\n\nThe orc sprite sheet is a 6×6 pixel art atlas (`renderer/assets/orc-sprite-atlas.png`, 3072×3072). Row layout:\n\n| Row | Animation |\n|---|---|\n| 0 | Sleeping |\n| 1 | Waking |\n| 2 | Typing |\n| 3 | Alarmed |\n| 4 | Celebrate |\n| 5 | Annoyed |\n\nSee `docs/sprite-atlas-prompt.md` for the generation prompt used with image models.\n","readmeFilename":"README.md"}