Your always-on coding companion. Never miss when Claude is done —
the pet sees every hook event and taps you on the shoulder with a sound.
Never re-explain your project — it remembers what you built, decided,
and fixed, and slips a ranked recap into every new session.
Never sit hunched for four hours — it prompts eye and wrist breaks and
demonstrates each stretch so you just mirror. Never miss a review or a
deploy — it watches your GitHub repos and alerts you the moment something
lands. 100% local. Open source. Free.
Claude Code runs in your terminal. If you tab away, you have no idea what Claude is doing — thinking? waiting? failed? done? The pet fixes that, then adds a memory brain, self-learning skills, and an ergonomics coach on top.
Live reactions
11 emotions triggered by real Claude Code hooks. Reading a file → cyan scanning eyes. Editing → blue sparkles. Bash → green arrow eyes. Success → 3 dings. Attention → 2 beeps. Failure → thud.
Memory brain
Every project you code in gets a local SQLite graph of decisions, conventions, fixes and gotchas. Each new Claude Code session gets a ranked ≤800-token context injection so Claude picks up where you left off.
Self-learning skills
Patterns reinforced 2× get promoted into real Claude Code SKILL.md files at ~/.claude/skills/. Levels compound: hatchling → apprentice → senior → master. Expertise carries across projects.
Ergonomics coach
Counts only real work time (not lunch). Prompts eye-breaks every 20 min, chin tucks every 30 min, wrist circles every 45 min. The pet demonstrates each exercise — you mirror it.
GitHub repo watcher NEW · v0.5
Add any GitHub repo — public or private. The pet polls for new commits, PRs, PR reviews, releases, CI runs, and deploys, then reacts with the matching sound + emotion. ETag-cached (quiet repos cost 0 rate-limit budget). Optional PAT unlocks 5000 req/hr.
Futuristic HUD dashboard
Click the pet to open the memory/ergonomics dashboard. Deep navy, cyan hairlines, corner brackets, monospace data readouts, force-directed animated graph, circular gauge meters.
100% local
Zero cloud, zero uploads, zero telemetry. Everything lives in ~/.claude/claude-pet/memory.sqlite on your machine, gitignored by default. 11 secret-pattern regexes scrub anything sensitive before write.
◆New in v0.5 · GitHub repo watcher
Point the pet at any GitHub repo — yours, an upstream you contribute to, a customer's product, an oncall service. When something happens, you hear it and see it, without ever opening a browser tab. No webhooks. No server. No sign-in.
What it watches
New commits — curious chirp + "N new commits on main by @user"
PRs opened / merged / closed — matched success or error tone
GitHub Actions runs — CI passes get a ✓, failures get a ✗
Deploy status — per-environment success or failure alerts
Issues opened — quiet chirp so you don't miss triage
Why it stays out of your way
ETag-cached polling — a quiet repo costs 0 rate-limit budget after the first poll
First-poll silent — adding a repo doesn't spam you with the last 30 events
Never twice — deduped by GitHub event id, one alert per real event
Per-type toggles — silence PushEvent on a chatty repo, keep review + deploy alerts
Rate-limit safe — 60 req/hr unauth (fine for 5 repos), 5000/hr with an optional PAT
Token stays local — stored only in ~/.claude/claude-pet/config.json (chmod 600), sent only to api.github.com
GITHUB · ACTIVITYLIVE
●12sCI: build-and-release passed
◆1m3 new commits on main by @octocat
●4m@reviewer approved PR #128
▲9mDeploy to production failed
◆14mPR #131 opened: fix auth race condition
●22mRelease v0.5.0 published
◆31mIssue #204 opened: sqlite lock on Win11
$claude-pet github watch nikhilagrima/claude-pet
$claude-pet github events --limit 20
◆The pet demonstrates every exercise
Break-reminder apps fail two ways: they fire when you're not working, and they don't tell you what to do. Claude Pet counts only real Claude Code activity, and when a break's due, the mascot performs the exact motion — you mirror it. Native SMIL animation, all rendered live below.
EYE BREAK · 20-20-20
CHIN TUCK · NECK
WRIST CIRCLES · RSI
REACH HIGH · POSTURE
WATER · HYDRATION
◆Install in 60 seconds
macOS, Windows, and Linux — one command each. The installer creates a permission-safe venv at ~/.claude-pet-venv/, wires Claude Code hooks, and starts the pet. From then on, every new Claude Code session auto-launches it.
macOS
Requires Python 3.10+ and Homebrew (the installer will install Homebrew for you if missing).
git clone https://github.com/nikhilagrima/claude-pet.git ~/claude-pet
cd ~/claude-pet
bash install.command
Linux
Requires Python 3.10+. The installer will sudo-install Cairo via apt / dnf / pacman.
git clone https://github.com/nikhilagrima/claude-pet.git ~/claude-pet
cd ~/claude-pet
bash install.sh
Windows (PowerShell)
Requires Python 3.10+. Cairo ships inside the cairosvg wheel — no extra install.
git clone https://github.com/nikhilagrima/claude-pet.git $HOME\claude-pet
cd $HOME\claude-pet
.\install.bat
Prefer a pre-built binary?
Grab the .app / .exe / Linux binary from the latest GitHub release. Drag to /Applications (macOS) or run directly.
One command. Auto-detects your install type (git clone vs pip), pulls the latest, restarts the running pet in place.
Update to the latest release
Idempotent — running when already on latest prints "up to date" and exits. Add --force to reinstall anyway.
claude-pet update
Or fresh-install over the top
Same as the first install — the installer is fully idempotent and safe to re-run.
cd ~/claude-pet && git pull && bash install.command
◆Under the hood
Cross-platform Qt window
PySide6 frameless, translucent, always-on-top. Works on macOS (accessory-app mode, no Dock icon), Windows, Linux (X11 + Wayland compositors).
Live SVG mascot
Every emotion is generated from bot_svg.py — dynamic colors, breathing, blink cycles, tier badges. Ergonomics animations are native SMIL, rendered by QSvgWidget.
Local Flask :5050
Tiny state server the pet polls at 2.5 Hz. Serves /state, /version, /break, /shutdown. Never talks to the network — localhost only.
SQLite memory + FTS5
Additive migrations from every version. Ranked injection = weight × recency × BM25 match. Skills promoted to real Claude Code skills at 2× reinforcement.
Idempotent installer
Safe to re-run. Detects broken hook paths and self-heals via claude-pet doctor. Self-replaces stale versions on upgrade so restarts aren't manual.
83 tests, 3 platforms
Every push runs the full suite on macOS + Windows + Linux CI. Every release tag builds .app / .exe / Linux binaries and attaches them to a GitHub release automatically.
◆Build your own pet
Claude Pet is MIT-licensed and made to be forked. Add a new mascot, a new exercise, a new integration — the extension points are deliberate and tiny. Adding a full new ergonomics exercise, for example, is a 6-line PR: drop an SVG in svgs/, append one row to exercises.py. Adding a new emotion is one entry in the EMOTIONS dict. That's it.
Fork the mascot
The pet is drawn live from SVG in src/claude_pet/bot_svg.py. Change the capsule color, swap the eye shapes, redesign it entirely — it's ~300 lines of pure Python-generated SVG, no assets to redraw.
Add an exercise
Drop your animated SVG in src/claude_pet/ergonomics/svgs/, then append one Exercise(...) row to exercises.py. The scheduler and overlay pick it up automatically.
Add an emotion
Every emotion is a one-line entry in EMOTIONS in bot_svg.py: eye kind, color, halo intensity, LED color. Ship a new state via POST /state and the pet reacts.
Integrate any tool
The pet listens on localhost:5050. Any tool that can POST /state or POST /break can drive it — CI notifications, deploy alerts, PR reviews, whatever you want.
Refine the memory brain
Ranking, distillation, skill promotion, secret redaction — every heuristic is small, tested, and easy to iterate. See src/claude_pet/memory.py and distill.py.
Ship a translation / theme
Dashboard strings are colocated in panel.py. The HUD palette lives in one NEON dict — swap it for a synthwave, retro-green, or pastel theme in ~30 minutes.
