Claude Pet is a free and open-source desktop companion developed by Byteflow.bot, designed specifically for developers using Claude Code. Claude Code runs in the terminal, and when users switch to other windows, it is often unclear what Claude is doing. Claude Pet uses a small robot mascot floating in the bottom-right corner of the screen, responding in real time to Claude Code hook events, using animated expressions and sounds to keep users informed of the status at all times.
Main capabilities
Real-time status reactions: The pet displays different expressions and sounds based on Claude Code events, such as purple spinning eyes indicating thinking, cyan scanning eyes indicating reading files, blue flashes indicating writing/editing code, a green down arrow indicating running bash commands, green ^^ eyes plus three short dings indicating task completion, red X eyes plus a low tone indicating task failure, a blue pixel circle plus two beeps indicating the user's attention is needed, a sleepy face plus Zzz indicating idle for 3 minutes, and starry eyes indicating the start of a new session.
Sound alerts: Three short dings play when a task is completed, two attention beeps play when input or permission is needed, and a low tone plays on failure, so users can know by sound when they need to return even if they have left the terminal.
Local graph memory (v0.3.0): Stores decisions, conventions, fixes, and cautions by project to ~/.claude/claude-pet/memory.sqlite. The data is fully local, not synced, and not packaged. The SessionStart hook outputs a ranked context block of no more than 800 tokens (weight x recency x FTS5 matching), so Claude can see important information in the first turn. If .ua/knowledge-graph.json exists (Understand-Anything format), it is imported as the authoritative source.
Self-learning skills: Patterns that recur at least 2 times are automatically promoted to real SKILL.md files under ~/.claude/claude-pet/skills/, with valid frontmatter, and Claude Code can automatically recognize them. Skill levels evolve from 🥚 Hatchling → 🐣 Apprentice → 🦉 Veteran → 🦄 Master.
Ergonomics coach (v0.4.0): Calculates actual working time based on Claude Code hook events, prompts for micro-breaks at appropriate times, and the pet demonstrates movements through animated SVG, with a countdown ring and completion/skipButtons. Includes eye rest every 20 minutes (20-20-20 rule), chin tuck every 30 minutes, wrist circles every 45 minutes, stretching every 60 minutes, and water reminder every 60 minutes. Timers pause when the pet enters a 3-minute sleep state, and are delayed by up to 5 minutes while typing to avoid interruptions. Configuration is located at ~/.claude/claude-pet/config.json. Note: This is not medical advice, only health guidance based on published ergonomics research.
GitHub repository monitoring (v0.5.0): You can add public or private repositories (private requires a token), and the pet will notify you when there are new commits, PR opened/merged/closed, PR reviews (approved/changes requested/commented), new releases, CI runs (passed/failed/cancelled), deployment status, or new issues. It uses polling instead of webhooks, so no public endpoint is needed; it uses ETag caching, so quiet repositories do not consume rate limits after the first poll; unauthenticated is 60 times per hour (5 repositories at 5-minute intervals is enough), and using a personal access token is 5000 times per hour; the first poll is silent, and only activity after adding is notified; events are deduplicated; and it can be toggled on or off by type. Repositories can also be added on the GITHUB tab of the dashboard.
How to use
Installation: A one-click installation script is provided. Use PowerShell on Windows, bash install.command on macOS, and install.sh on Linux. You can also download the latest release ZIP and double-click the installation file for the corresponding system (install.command for macOS, install.bat for Windows, install.sh for Linux), then wait about 60 seconds. macOS also provides a prebuilt Claude Pet.app; drag it into /Applications and double-click it, no Python required. The installer checks for Python 3.10+, installs Homebrew (on macOS if missing), installs the Cairo graphics library, creates a Python virtual environment, installs the claude-pet package, writes Claude Code hooks to ~/.claude/settings.json, and starts the mascot in the background. The installer is idempotent and safe to run repeatedly.
Interaction: Click the mascot to open the HUD dashboard (Projects / Graph / Skills / Stats / Ergo tabs); drag to move its position; right-click to open the context menu, which includes Hello / Working / Celebrate / Sleep (reaction pokes), Take a break now (immediately open the ergonomics overlay), Snooze breaks 30 min, Turn Ergonomics ON/OFF, Reset position / Quit. After 3 minutes of idleness, the mascot falls asleep and pauses all ergonomics timers; during idle periods, it briefly displays the current time every 30 seconds. The mascot is always on top of all applications, including full-screen applications and other macOS spaces.
Updates: One command automatically detects the installation type, pulls the latest version, and restarts the pet. Editable installations (git clone) run git pull --ff-only and refresh pip; regular pip installations run pip install --upgrade git+https://github.com/nikhilagrima/claude-pet.git Then restart. Idempotent; if it is already up to date, it will show already up to date; add --force to force reinstall.
Build: Uses PyInstaller, cross-compilation is not supported, and it must be built on the target operating system.
Use cases
Suitable for developers who use Claude Code for development, want to be aware of Claude's status without staring at the terminal, need project-level local memory and automatic skill accumulation, care about ergonomic health, and need to monitor GitHub repository activity.
Limitations and notes
System requirements: Python 3.10 or newer; macOS 11+ (Big Sur or newer); Linux requires an X11 or Wayland compositor (GNOME, KDE, and Sway have been tested). The materials do not clearly list specific version requirements for Windows support.
Data and privacy: 100% local, no cloud, no embeddings, no vector database, no new daemon. 11 secret-pattern regexes redact sensitive information before it is written to disk. The .sqlite file has been added to .gitignore, and the package includes a fresh empty memory.
Sound: macOS uses built-in system sounds; Windows falls back to Windows Notify System Generic.wav; Linux uses freedesktop's complete.oga / dialog-error.oga; if none are found, a bundled fallback WAV is played.
Data flow: Claude Code event → hook.py → HTTP POST to :5050 → the pet polls and renders the new expression.
License: MIT © 2026 Byteflow.bot.
Ergonomic features are not medical advice, do not diagnose or treat any condition, and if you have pain, please consult a professional.
Other feature details, pricing, platform support, and other information not provided in the materials are not yet available.
