Claude Pet
A desktop companion that exposes Claude Code activity while adding local project memory, repository alerts, and activity-aware break coaching.
- Source repo
- nikhilagrima/claude-pet
- Stars
- ★ 15
- Last updated
- 3mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specificClaude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer who switches from Claude Code to a browser, Slack, or another editor can use the floating expressions and sound patterns to distinguish thinking, file access, code edits, shell commands, input requests, completion, and failure.
- Not a fit if
- Developers who don't use Claude Code and rely on ChatGPT or Codex instead
- Teams unwilling to run a persistent desktop window and local Flask service on port 5050
- Environments that must stay fully offline or forbid writing Claude settings and local SQLite files
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Claude Pet is a local desktop companion for Claude Code users, not a general-purpose coding agent that works independently. Claude Code hooks send session and tool events through hook.py to a local Flask service on port 5050, while a transparent PySide6 window renders animated reactions and plays sound cues. Its memory subsystem stores project decisions, conventions, fixes, gotchas, and notes in a local SQLite graph, then injects a ranked context block of up to 800 tokens when a new session starts. Clicking the mascot opens a HUD covering Projects, Graph, Skills, Stats, ergonomics, and GitHub activity, while the CLI handles lifecycle, memory, monitoring, and break controls. The GitHub watcher polls commits, pull requests, reviews, releases, Actions runs, deployments, and issues; private repositories and higher rate limits require a personal access token. It is best suited to developers who use Claude Code regularly and are comfortable running a persistent local desktop process that writes hooks and project memory.
The installer checks for Python 3.10+, installs Cairo, creates a virtual environment, installs claude-pet, and writes Claude Code hooks into ~/.claude/settings.json. The runtime path is Claude Code event → hook.py → HTTP POST to the local :5050 service → polling and rendering by the pet; completion, attention, and failure states also produce distinct sounds. app.py supplies the frameless PySide6 window, server.py holds current state, bot_svg.py generates 11 animated emotions, and cli.py exposes lifecycle, memory, ergonomics, and GitHub commands. The memory system writes project facts and user notes to ~/.claude/claude-pet/memory.sqlite, can ingest .ua/knowledge-graph.json, and ranks SessionStart context using weight, recency, and FTS5 matching. Patterns reinforced at least twice can be promoted into SKILL.md files placed in Claude Code's skill discovery path. The GitHub watcher polls with ETag caching, suppresses historical events on its first poll, deduplicates subsequent events, and turns repository activity into alerts; the ergonomics component opens animated, timed exercise overlays based on recorded active work.
- A developer who switches from Claude Code to a browser, Slack, or another editor can use the floating expressions and sound patterns to distinguish thinking, file access, code edits, shell commands, input requests, completion, and failure.
- A solo developer returning to several long-running projects can preserve decisions, conventions, fixes, and next-step notes locally and have relevant context supplied at the beginning of later Claude Code sessions.
- A repository maintainer can receive desktop notifications for commits, pull-request transitions, reviews, releases, CI runs, deployments, and new issues without operating a public webhook endpoint.
- A programmer working long terminal sessions can use activity-aware reminders for eye breaks, chin tucks, wrist circles, reaching, and hydration, with timers paused while the pet is idle.
- A contributor who wants a customizable desktop mascot can extend the documented PySide6, Flask, SVG, CLI, and PyInstaller structure with additional emotions, exercises, dashboard tabs, integrations, or themes.
How do you install or deploy this agent?
The documented runtime requirements are Python 3.10 or newer and either macOS 11+, Windows 10+, or Linux with X11/Wayland. Installation also brings in Cairo and modifies ~/.claude/settings.json to connect Claude Code hooks.
On macOS or Linux, clone the repository and run the installer:
git clone https://github.com/nikhilagrima/claude-pet.git ~/claude-pet && cd ~/claude-pet && bash install.shThe macOS-specific instruction is:
bash install.commandOn Windows PowerShell:
git clone https://github.com/nikhilagrima/claude-pet.git $HOME\claude-pet
cd $HOME\claude-pet
.\install.batAfter installation, the first foreground invocation can be used to see the process output and mascot directly:
claude-pet runNo credential is required to watch public GitHub repositories. Supply a personal access token for private repositories or the documented 5,000-requests-per-hour allowance:
claude-pet github token ghp_yourPATHow do you use this agent?
Start the pet as a detached background process:
claude-pet startThen use Claude Code normally; the installed hooks forward its events to the local service. Click the mascot to open the HUD, drag it to reposition it, or right-click for reaction controls, an immediate break, a 30-minute snooze, the ergonomics toggle, position reset, and quit.
Diagnose and repair hook paths:
claude-pet doctorInspect project memory, add a note, and review the next SessionStart context block:
claude-pet memory
claude-pet note "Working on the auth refactor, next step is JWT rotation"
claude-pet contextRegister and inspect a GitHub repository watcher:
claude-pet github watch facebook/react
claude-pet github list
claude-pet github check
claude-pet github eventsInspect or trigger ergonomics coaching:
claude-pet ergonomics status
claude-pet ergonomics break-now
claude-pet ergonomics statsUpdate or stop the application:
claude-pet update
claude-pet stopWhat are this agent's strengths and limitations?
- It maps specific Claude Code states—thinking, reading, writing, shell execution, attention, completion, and failure—to recognizable animation and sound cues that remain visible away from the terminal.
- Project memory remains in local SQLite without cloud storage, embeddings, or a vector database, and 11 secret-pattern regular expressions redact sensitive values before they reach disk.
- GitHub monitoring needs no public webhook endpoint and combines silent first polling, event deduplication, per-event toggles, and ETag caching to reduce unnecessary API usage.
- Ergonomics timing is driven by observed Claude Code activity: three minutes of idleness pauses timers, and reminders can be deferred while the user is typing.
- The project supplies installers and PyInstaller build scripts for macOS, Windows, and Linux, and reports 112 passing tests across those three platforms.
- Its core event feed and context injection are tied to Claude Code hooks; no native route is documented for ChatGPT, Codex, Claude.ai, the OpenAI API, or the Claude API.
- Adoption adds a persistent PySide6 desktop window and local Flask service on port 5050, plus writes to Claude settings, a virtual environment, SQLite storage, and skill directories.
- Source installation requires Python 3.10+ and Cairo; Linux additionally needs X11 or Wayland, and binaries must be built on each target operating system because cross-compilation is unsupported.
- GitHub monitoring depends on network polling. Anonymous access is documented at 60 requests per hour, while private repositories and the higher limit require storing a personal access token.
- Automatic context injection and promotion of repeated patterns into discoverable skills can influence later Claude Code sessions, so teams should evaluate memory quality and local-data governance before rollout.
- The ergonomics module is wellness guidance rather than medical diagnosis or treatment.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Claude Pet This agent | 53 · Major gaps | Desktop appFree | ★ 15 | 3mo ago | Python | Claude Code |
| projectmem Coding Memory | 73 · Some gaps | CLIFree | ★ 878 | 7d ago | Python | Codex · Claude Code · Claude.ai |
| Citadel | 84 · Good | Agent plugin / skillFree + model costs | ★ 927 | 4d ago | JavaScript | Codex · Claude Code |
| mex Project Memory | 84 · Good | CLIFree | ★ 1.8k | 4d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The app binds locally to 127.0.0.1, protects write endpoints with a shared token, describes local SQLite memory, and documents the event-to-UI flow; this supports ordinary-use access control and visibility. Deductions: the installer writes Claude Code settings and starts a background process, GitHub polling makes network requests, and the PAT is passed through a command line; secret-pattern redaction is claimed in the README without implementation detail in this sample; dependencies have minimum versions but no lock or security policy; on Windows the stop command can terminate every python.exe, while uninstall and recovery guidance is brief; Byteflow.bot is named as author, but its identity is unverified and maintenance/update responsibility is unclear.
The README and package metadata disagree on version (v0.5.0 versus 0.7.5), and the README describes three success beeps while the shown code configures one. Dependencies and installation requirements are fairly specific, and the packet includes cross-platform workflows and test samples. Deductions: these consistency gaps weaken documentation reliability; some exceptions are silently swallowed, and update failures lack fuller recovery guidance.
The product targets Claude Code users and coding workflows, describing event reactions, memory, ergonomics reminders, GitHub monitoring, and multiple operating systems. Deductions: boundaries are partly stated, including local operation, Wayland limits, and a non-medical disclaimer, but permissions, data handling, and integration triggers are not consolidated; trigger details are spread across the docs; platform behavior differs and cannot be fully confirmed from this sample.
The README covers installation, CLI, architecture, build, update, uninstall, contribution, and limitations, and the license file is complete. Deductions: version and changelog claims conflict with package metadata; this sample cannot establish stable naming or a clear maintainer update path; some installation methods rely on system package managers with limited detail.
The pet turns Claude Code activity into animated and sound cues, while memory injection, break reminders, and GitHub alerts add practical functions. Deductions: utility is mainly asserted in the README and lacks user outcome evidence in this packet; an always-on-top window, polling, and multiple reminders may add distraction or upkeep, with no quantified cost or explicit default tradeoff.
The architecture, CLI, dependencies, workflows, and some tests support specific implementation claims, and the README states limitations and a medical disclaimer. Deductions: the test sample covers only some paths and cannot corroborate the broad feature and platform claims; performance, safety, and feature guarantees are often asserted without consistently separating observed facts, design intent, and inference.
- On Windows, the stop command may affect other Python programs. Review how settings files, background processes, and a GitHub PAT are handled before installation or updates.
- The README version disagrees with package metadata, and its sound description differs from the shown code; confirm behavior against the installed revision.
- Memory and ergonomics features involve project activity records and health-related prompts. This sample is insufficient to verify complete retention, redaction, and reminder behavior.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/claude-pet)<a href="https://followagents.com/en/agents/claude-pet"><img src="https://followagents.com/badge/claude-pet.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Full Changelog: https://github.com/nikhilagrima/claude-pet/compare/v0.6.1...v0.7.0View on GitHub ↗ -
Release notes excerpt
Full Changelog: https://github.com/nikhilagrima/claude-pet/compare/v0.6.0...v0.6.1View on GitHub ↗ -
Release notes excerpt
Full Changelog: https://github.com/nikhilagrima/claude-pet/compare/v0.5.11...v0.6.0View on GitHub ↗
FAQ
Does it upload project memory to a cloud service?
~/.claude/claude-pet/memory.sqlite, and the project states that it uses no cloud service, embeddings, or vector database. The separate GitHub watcher still makes network requests to GitHub.Is a GitHub token mandatory?
What local changes and permissions should I expect?
~/.claude/settings.json, and stores configuration, memory, or generated skills under ~/.claude/claude-pet/ and ~/.claude/skills/.What can I do if Claude Code events stop producing the right reaction?
claude-pet doctor to diagnose and automatically repair broken hook paths. Running claude-pet run in the foreground also makes process output directly visible.Does uninstalling leave a background daemon?
claude-pet stop, claude-pet uninstall-hooks, and pip uninstall claude-pet. The project states that this leaves no daemon, LaunchAgent, or scheduled task.Thanks — we use this to improve the page.