claudeers.
// Developer Tools

claude-desktop-pet

A tiny pixel Claude on your desktop that reacts to everything Claude Code is doing. Windows, Electron.

// Developer Tools[ cli ][ api ][ desktop ][ web ][ claude ]#claude#claude-code#desktop-pet#electron#pixel-art#windows#devtools◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
99/100
last commit about 1 month ago
last release about 1 month ago
releases 3
open issues 0
// star history

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up claude-desktop-pet (git-clone project) into my current project.
Found on https://claudeers.com/claude-desktop-pet
Repo: https://github.com/Harriszed/claude-desktop-pet
Homepage/docs: —
Detected install method: git-clone → git clone https://github.com/Harriszed/claude-desktop-pet
Category: devtools. Platforms: cli, api, desktop, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or clone
git clone https://github.com/Harriszed/claude-desktop-pet

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageJavaScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

Claude Desktop Pet

A tiny pixel Claude that lives on your desktop and reacts to everything Claude Code is doing.
Thinking, reading, writing, running tests, failing, finishing, or just waiting for you.

Watch the Claude Desktop Pet promo: Claude Code at a glance
Watch the 55-second promo · Sound on · Live activity, sessions, helpers, usage, weather and effects

Current desktop pet recorded with day and night effects, task-card delegation and live helpers

What it does

A small always-on-top card sits in the corner of your screen. Whatever Claude Code is up to, the pet acts it out, with a speech bubble saying what it's touching right now.

The pet and its helpers use the extended pixel activities from Mascot Studio v1.7.0, with the earlier v1.6.0 walk restored. When idle, Claude randomly switches between stretching, looking around and a quiet breath, without repeating the same animation immediately. Breathing and looking around are each slightly more likely than stretching. Each finishes one or two complete loops; live activity interrupts it. Reduced motion stops idle switching. Delegating Claude puts on shades and conducts floating task cards; actual sub-agents appear separately below. Idle gags play their full 10–14 second sequences; incoming Claude Code activity interrupts them.

Sleeping uses Mascot Studio v1.7.2's blue nightcap, gentle bob and drifting Zs.

Pet states

  • Runs off your Claude Code hooks. It just listens, no file watching.
  • Speech bubbles show the current action (Editing App.tsx, npm test, Build failed).
  • Multiple sessions. Several Claude Code windows show as coloured chips; click one to jump to that window.
  • Task progress. A little bar follows Claude's to-do list.
  • Usage at a glance. 5-hour and 7-day usage with time until reset. Set Settings > Claude Code > Usage refresh to 1, 5 or 15 minutes, or 1 hour; the default is 5 minutes.
  • Context warning. Tells you when a session's memory is nearly full.
  • Sub-agents. Helpers appear as tiny Claudes underneath; click one for details.
  • Local weather and time of day change the scenery behind it.
  • Random gags. Every so often, when idle, it does something silly. See below.

Night scene with fireflies, stars and two active sub-agents

Random gags

When Claude is idle, it occasionally does an AI-flavoured bit. Ten so far:

claude-desktop-pet
Coffee. Always coffee.
claude-desktop-pet
Deploying to prod...
claude-desktop-pet
*ships it*
claude-desktop-pet
Buffering...
claude-desktop-pet
Totally real. Trust me.
claude-desktop-pet
Counting tokens...
claude-desktop-pet
Context window: feeling full
claude-desktop-pet
Thinking really hard...
claude-desktop-pet
Hello, fellow AI
claude-desktop-pet
Fine-tuning myself...

Turn them off with Idle chatter in Settings, or trigger one with Play a random gag.

Install

Download the latest release

PlatformDownloadSetup
Windows 10/11Setup-x64.exeRun the installer, then launch from the desktop or Start menu.
macOS, Intel or Apple Siliconmac-universal.dmgDrag the pet into Applications, then open it.
Linux x64linux-x86_64.AppImage or linux-amd64.debMake the AppImage executable and run it, or install the Debian package.

No Node.js or Git needed for these downloads. Open Settings > Connect Claude Code, then restart your open Claude Code sessions. The connection backs up ~/.claude/settings.json, preserves other hooks and keeps your existing status line.

Setup: click Connect Claude Code, then restart your Claude Code sessions

These are unsigned community builds. Windows may show a SmartScreen prompt. macOS may require System Settings > Privacy & Security → Open Anyway after your first launch attempt; managed Macs may block unsigned apps. Check that your download came from this repository. Code signing and notarisation require maintainer certificates.

Right-click the pet or its tray/menu-bar icon to open Settings. Enable Start at login there if you want it ready whenever you sign in. On Linux, some desktops need a tray extension; Settings is also available by right-clicking the pet.

Platform notes

  • macOS: fullscreen detection and clicking session chips may need Accessibility and Automation access in System Settings. Relaunch after granting access. Fullscreen detection uses native fullscreen state.
  • Linux X11: fullscreen detection uses xprop, and clicking session chips uses wmctrl. Install these with your distribution's package manager if needed (for example, sudo apt install x11-utils wmctrl).
  • Linux Wayland: window focus and fullscreen detection are unavailable because Wayland restricts access to other apps. Window stacking depends on your compositor.
  • Linux AppImage: keep it in a permanent folder before enabling Start at login. Some distributions require FUSE compatibility packages to run AppImages.
  • Usage readout: the credential-file method depends on how Claude Code stores its login. Where those credentials aren't exposed (for example some macOS Keychain logins), the hook status line can supply usage instead. A pre-existing status line is always preserved.

Run from source

For development, use Node.js 22.12+, Git and Claude Code:

git clone https://github.com/Harriszed/claude-desktop-pet.git
cd claude-desktop-pet
npm install
npm run install-hooks
npm start

On Windows, you can double-click Start Pet.vbs after setup to launch without a terminal. On macOS and Linux, use npm start. Restart open Claude Code sessions after connecting. Hooks can also be connected from Settings.

Remove

First choose Settings > Disconnect, then restart open Claude Code sessions and quit the pet. Turn off Start at login before uninstalling. Source installs can use npm run uninstall-hooks. The Windows uninstaller preserves your preferences for a future reinstall.

Updating

The pet checks once a day. Check for updates is also in Settings and the tray menu.

  • Windows installer and Linux AppImage: in Settings, choose Check for updates. The same button becomes Download update, shows download progress, then becomes Restart and install. This replaces the installed app and reopens it, keeping your preferences. Updates are never downloaded or installed without your choice. The tray menu also offers updates.
  • macOS and Linux Debian package: the update check opens the latest release. Replace the app or install the new package. Unsigned macOS apps cannot use the signed-app update mechanism.
  • Source install: quit the pet first, run the commands below in the project folder, then relaunch. Quitting first lets npm replace the Electron runtime on Windows.
git pull
npm install

Preferences live outside the install folder and survive updates. Moving the app? Use Settings > Repair connection to refresh your Claude Code hooks.

Settings

PreferenceWhat it does
Connect / repair / disconnectManage Claude Code hooks without a terminal
Test connectionVerify the configured pet hook can run and reach this app; shows repair steps if it fails
Usage refreshRefresh 5h and 7d figures every 1, 5 or 15 minutes, or every hour
Pet sizeLarge, medium or small
Compact modeA smaller strip of current activity
Always on topKeep the pet above other windows
Hide in fullscreen appsGive supported fullscreen apps the whole screen
Move to a cornerPosition the pet on its current screen
Idle chatterRandom quips and gags
Weather effectsLocal rain, snow and fog
Completion chimeOptional quiet chime when Claude finishes; off by default
Chime volume / Test chimeAdjust and preview the sound
Start at loginLaunch when you sign in
Visual effectsMaster switch, night sky/fireflies, atmosphere, work sparks and completion sparkles
Retro scanlinesOptional faint CRT texture; off by default
Effects intensityAdjust the density and strength of decorative effects
Boot sequence / PreviewShort wake-up and wave on launch; live activity interrupts it
Check for updatesFind and install available updates

Changes save immediately. The tray keeps quick actions for Show / hide, Settings, corner placement, updates, previews and Quit. Drag the card by its header or footer, click the character for details, and click the faint arrow to cycle sizes.

Decorative effects stay inside the pet's scene. Night effects appear on clear nights; leaves appear in September through November. The weather switch works separately. Animated effects pause while the window is hidden and are skipped when your system requests reduced motion. Turning off visual effects also skips the boot sequence; compact mode skips scene effects.

Current settings with connection test, usage refresh, visual effects, boot preview and update controls

Blue nightcap sleeping animation with drifting Zs and a night sky

Rain in the current pet scene Snow in the current pet scene

Building and releasing

npm test
npm run test:smoke       # live Electron checks on Windows, isolated from your preferences
npm run test:vfx         # effect toggles, boot interruption and restart persistence
npm run dist:win         # Windows installer
npm run dist:mac         # universal DMG + ZIP; run on macOS
npm run dist:linux       # AppImage + Debian package; run on Linux

Builds are written to dist/. See the release guide for GitHub publishing, signing and the build workflow. A version tag builds all three platforms and publishes a Release only after all builds and unit tests succeed. The README's screenshots and short GIF above show the pet in action.

Privacy and how it works

  • Claude Code hooks send small events (state, tool name, file name) to a local server on 127.0.0.1:47821. Nothing leaves your machine for that.
  • Usage readout: to show your 5h / 7d usage, the app reads your Claude login token from ~/.claude/.credentials.json and asks Anthropic's usage endpoint at your chosen refresh interval (5 minutes by default). The token is not stored or sent anywhere else. That endpoint is undocumented and may change or stop working.
  • Weather uses your approximate location from a public weather service.
  • Settings are saved outside the installation: %APPDATA%\claude-desktop-pet\window.json on Windows, ~/Library/Application Support/claude-desktop-pet/window.json on macOS, and ~/.config/claude-desktop-pet/window.json on Linux (or your XDG config directory).
  • Release checks contact GitHub. An update is downloaded only after you select it. The completion chime is generated locally; no audio is uploaded or downloaded.

Project layout

FilePurpose
main.jsWindow, tray, hook server, usage polling
index.htmlPet UI and animation logic
settings.html / settings.jsSettings window
platform.jsStartup, fullscreen detection and session focus
updates.jsRelease checks and installer updates
animation-catalog.js / idle-animations.jsPinned artwork timing and weighted idle rotation
vfx.js / vfx.cssScene effects, boot sequence and reduced-motion support
connection-test.js / usage-refresh.jsConnection diagnostics and usage polling schedule
sounds.jsLocally generated completion chime
hook.jsTiny script Claude Code runs on each event
install-hooks.jsAdds or removes the hooks
assets/Pixel animations (SVG)

Add your own gag by dropping a gag-name.svg in assets/ and adding a line to the GAGS list in index.html.

Changelog

See CHANGELOG.md for what changed in each version.

Credits and licence

This is an unofficial fan project. It is not made by or affiliated with Anthropic. The Claude character belongs to Anthropic.

The pixel mascot artwork builds on Ayotomiwa Wale-Durojaye's mascot demo and his Codrops article. The code is MIT licensed. The character artwork in assets/ is not covered by that licence. See NOTICE.md.

// faq

What is claude-desktop-pet?

A tiny pixel Claude on your desktop that reacts to everything Claude Code is doing. Windows, Electron.. It is open-source on GitHub.

Is claude-desktop-pet free to use?

claude-desktop-pet is open-source under the MIT license, so it is free to use.

What category does claude-desktop-pet belong to?

claude-desktop-pet is listed under devtools in the Claudeers registry of Claude-compatible tools.

45 views
★ 14 stars
unclaimed
updated about 1 month ago

// embed badge

claude-desktop-pet on Claudeers
[![Claudeers](https://claudeers.com/api/badge/claude-desktop-pet.svg)](https://claudeers.com/claude-desktop-pet)

// retro hit counter

claude-desktop-pet hit counter
[![Hits](https://claudeers.com/api/counter/claude-desktop-pet.svg)](https://claudeers.com/claude-desktop-pet)

// reviews

// guestbook

0/500

// related in Developer Tools

🔓

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Curs…

// devtoolsaffaan-m/⟨JavaScript⟩★ 307,864◷ MIT[ claude ]
🔓

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

// devtoolsDietrichGebert/⟨JavaScript⟩★ 187,728◷ MIT[ claude ]
🔓

AI coding assistant skill (Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more). Turn any folder of code, SQL schemas, R scripts, shell scripts, docs,…

// devtoolssafishamsi/⟨Python⟩★ 147,800◷ MIT[ claude ]
🔓

Use Garry Tan's exact Claude Code setup: 23 opinionated tools that serve as CEO, Designer, Eng Manager, Release Manager, Doc Engineer, and QA

// devtoolsgarrytan/⟨TypeScript⟩★ 140,465◷ MIT[ claude ]
→ see how claude-desktop-pet connects across the ecosystem