It sits in the corner, watches your cursor, kneads the keyboard when you type, purrs when you pet it, and stretches like mochi when you drag it. Prefer a dog? Switch species from the tray and you get a real one: a Black Lab with a wagging tail that reads your pet's mood, a play bow instead of a hunting crouch, and a tennis ball it will actually chase down and bring back. A desktop pet built from scratch: nearly every sprite, animation, and sound is original and procedural.
-4C566A?style=flat-square&labelColor=15161d){kind=icon}
Every frame above is rendered from code, not screen capture. MP4 version.
The browser demo runs the real renderer: pet it, type at it, scroll to see it react, and wait for the butterfly.
In action · What it does · Quick start · Controls · AI agents · Privacy · Docs · Contributing
 Reacts when you scroll |
 Kneads when you type |
 Plays with a butterfly |
 Noms a treat |
 Sings and meows |
 Purrs when you pet it |
 Stretches like mochi |
 Pounces on the cursor |
 14 coats, plus your own |
| It reacts to you | Petting, dragging, typing, scrolling, and cursor play each get their own response, gated by an internal mood model that runs from calm up to zoomies and back. |
| 15 coats, one shape | 14 cat coats and a Black Lab, all recolored at draw time from one role-coded sprite. Design, import, and export your own. |
| No spare frames | Every animation is composed into that sprite, limbs included, so all 15 coats across both species get every pose in their own colours without shipping a single extra image. |
| Zero audio files | The meow, the bark, the purr, the pant, and an endlessly improvising lo-fi jam are all synthesized live with Web Audio. |
| It keeps you on track | Break and Pomodoro timers, repeating reminders, a pinned note, IMAP unread-mail alerts, and calendar nudges, all delivered by your pet. |
| It watches your agent | It knows when your coding agent is thinking, working, or done, and reacts with its paws. Hook configs ship for five agents. |
| It stays out of the way | A transparent, click-through overlay that sits above every window. Only your pet is clickable. |
Fourteen coats, one shape. Every pose in every coat, recolored from a single role-coded sprite at draw time.
Pick your species from the tray (Pet > Cat / Dog); each keeps its own coat. The dog is not a recoloured cat. It has its own sprite module, with a muzzle that protrudes past the skull line, floppy ears, a broader chest, and a straight otter tail.
| Cat | Dog | |
|---|---|---|
| Excited | hunting crouch, ears back | play bow: chest down, rump up, tail flagged |
| Play | bats a butterfly | fetch: chases the ball down, carries it home, drops it |
| After exertion | grooms | pants, tongue out |
| Reward | a fish treat | a tennis ball |
Full comparison, and every interaction, in the feature guide.
The pet doubles as a quiet productivity companion, and it works out when to leave
you alone. Focus Guard reads "busy" from a calendar event that is actually
happening now, from Quiet Hours, or from Work mode, then parks the pet and holds
email, reminders and agent messages back rather than meowing into your
screen-share. Nothing is thrown away: when you are free it sums the lot up in one
line. On top of that sit break and Pomodoro timers, repeating reminders, a pinned
note, IMAP mail alerts, .ics calendar nudges, and a live lo-fi jam.
The Windows installer is the easy path. No git, no Node, just run it:
You can also play with the cat in your browser before installing anything.
Important
Your OS will warn you the first time, and that is expected. The builds are not code-signed yet, because a certificate costs real money for a free app.
- Windows: SmartScreen shows a blue "Windows protected your PC" screen. Click More info, then Run anyway.
- macOS: Gatekeeper refuses a double-click. Try to open it once, then go to System Settings > Privacy & Security and click Open Anyway. (On macOS 14 and earlier, right-clicking the app and choosing Open also works; macOS 15 removed that shortcut.)
Would rather not? Play it in your browser (the real renderer, nothing to install) or run it from source below. Both skip the installer entirely.
What the app does on your machine is documented in Privacy and SECURITY.md: the keyboard hook forwards a single "a key was pressed" boolean and never what you typed.
To run from source, on any platform, you need git and Node 20 or newer:
git clone https://github.com/JOhnsonKC201/pixelpets.git
cd pixelpets
npm install
npm startEither way your pet appears in the corner and registers itself to start at login.
npm run autostart:off turns that off, and the installed version uninstalls like
any other program, from Windows Settings > Apps. Running from source has two
platform notes (a silent Windows launcher, and the macOS Accessibility grant)
covered in the development guide.
| Action | What it does |
|---|---|
| Drag the cat (hold left) | Stretches it like mochi; it drops where you release |
| Right-click the cat | Cycles to the next coat pattern |
| Tap the cat | A quick pet: happy eyes, hearts, a chirp |
| Rest cursor on its head | Happy eyes, floating hearts, and a purr |
| Rest cursor on its body | Leans and arches into your hand, tail up, trilling |
| Type (any app) | Front-paw kneading; fast typing overheats it |
| Scroll (any app) | Climbs a yarn rope, or rears up and swipes at a blowing leaf |
| Double-click the cat | Opens Settings (name, timers, reminders, coat) |
| Tray icon | Settings, Start break now, coat picker, play area, sound and hunt and mood toggles, Quit |
Settings persist to settings.json in your per-user app-data folder
(%APPDATA%/pixelpets/ on Windows, ~/Library/Application Support/pixelpets/ on
macOS). An install that predates the rename is migrated across on first launch.
Timers and reminders only fire while pixelpets is running, and reminder times use
your local clock.
The cat reacts to a coding agent's work status, and it uses its paws to do it. It
raises a paw to its chin to ponder while an agent like Claude Code, Codex, or
Cursor thinks, taps a paw along with a spinner while it works, and does a happy
hop and meow when it finishes. Any tool can signal it by running the bundled
helper, which writes a tiny status file the cat watches
(%TEMP%/pixelcat-agent.state):
node agent-hook.js thinking # ponders, paw to chin + "…" bubble
node agent-hook.js editing # taps a paw + "working" spinner
node agent-hook.js error # the cat startles (flinch)
node agent-hook.js done # happy hop + meow
node agent-hook.js idle # back to normalReady-to-use configs for Claude Code, Codex CLI, Cursor, Antigravity and Kiro
live in integrations/, and npm run hook -- <agent> prints
yours with the absolute path already filled in. The helper is hook-safe: it
drains stdin and replies {"continue": true}, so it never blocks or alters your
agent.
The richer status reactions were inspired by the open-source AI desktop pets openpets (MIT) and clawd-on-desk (AGPL-3.0). Ideas only; all code here is original to pixelpets.
Your pet reacts to your typing and scrolling, which means it listens to global
input events, so here is the plain statement: input is used only to trigger
animations, in the moment, on your machine. Keystrokes are never logged, stored,
or sent anywhere. There is no telemetry and no auto-update. The app makes no
network connections at all unless you set up the optional mail or calendar
alerts, and those talk only to the servers you point them at, from isolated
worker processes. Your IMAP app password is stored encrypted at rest (Electron
safeStorage) and never written to settings.json.
| Guide | What is in it |
|---|---|
| Features | Every interaction, coat, mood, sound, and productivity feature |
| Custom coats | Designing, hand-editing, and sharing your own coat |
| How it works | One sprite covering 15 coats, and the project layout |
| Development | Running from source, building installers, visual QA |
| Frame pack | Painting a pose by hand and importing it |
| Agent hooks | Wiring the pet to Claude Code, Codex, Cursor, Antigravity, Kiro |
| iPad terminal | A real terminal for this machine, driven from an iPad |
npm start # run the app
npm test # 200+ tests, no Electron and no GPU required
npm run lint # what CI runs, alongside the tests and a real boot check
npm run poses:cat # contact sheet: every activity x every coat, for visual QAThe overlay is GPU-composited, so ordinary screenshots cannot capture it. Visual changes are reviewed with those contact sheets instead. The full command list, build instructions, and the macOS beta checklist are in the development guide.
Bug reports, ideas, and PRs are all welcome. Start with the contributing guide; the security policy covers reporting a vulnerability privately.
If you own a Mac, running the beta checklist and opening an issue with whatever you see is the single most useful contribution right now: the port is code-complete and the builds are ad-hoc signed, but nobody has run one on real Apple hardware.
Custom coats and desk setups belong in Discussions, and release history lives in the changelog.
Made for fun. All art, code, and sound are original; the meow and purr are synthesized in code, with no audio files. pixelpets is inspired by, not copied from, Comnyang: no Comnyang assets, sprites, audio, or branding are used.