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
- ★ 14
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 64/100 · Some gaps
At a glance
- Works with
- Platform-specificClaude Code
- 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.
- Main limitation
- 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.
- Source review
- 64/100 · Some 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 | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Claude Pet This agent | 64 · Some gaps | ★ 14 | 1mo ago | Python | Claude Code |
| projectmem Coding Memory | 74 · Some gaps | ★ 828 | 9d ago | Python | Codex · Claude Code · Claude.ai |
| mex Project Memory | 71 · Some gaps | ★ 1.6k | 5d ago | TypeScript | Codex · Claude Code |
| Citadel | 60 · Some gaps | ★ 923 | today | JavaScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows token-protected local write endpoints, asserted local-only memory, pre-storage secret-pattern redaction, and documentation of installation, GitHub polling, configuration paths, and major external effects. Deductions apply because installation can add system software, modify Claude settings, and start a background process, while automatic memory and context injection are not confirmed per event. PAT scope, storage protection, and log redaction details are not shown. Dependencies use broad lower bounds without a lockfile, hashes, vulnerability scanning, or update audit. Removal and deletion commands exist, but complete cleanup of configuration, tokens, and data and any update rollback are not documented. Authorship and MIT attribution are clear, while ergonomics sources are named only as organizations without traceable citations.
Cross-platform CI, declared runtime dependencies, and regression tests for authorization, error logging, context budgets, and event cooldowns provide ordinary-use reliability evidence. Deductions apply because the README presents v0.5.0 while package metadata declares v0.7.5, and the claim of 112 passing tests cannot be independently established from the supplied excerpts. Failure handling is represented only by logging tests, the doctor description, and limited HTTP status checks; comprehensive user-facing diagnostics, network backoff, and database recovery are not shown.
The intended developer audience and coding, CLI, desktop, memory, ergonomics, and repository-monitoring scenarios are described thoroughly, justifying full credit for audience and scenarios. Boundaries cover local storage, polling instead of webhooks, the medical disclaimer, and lack of cross-compilation, but absolute local-only language sits awkwardly beside GitHub network access. Event mappings, idle thresholds, deferral, and cooldown tests support trigger precision, although the complete trigger implementation is absent. Three desktop platforms and minimum versions are documented, but Linux desktop variability, permissions, and headless constraints are not treated comprehensively.
The README clearly organizes installation, operation, CLI commands, architecture, builds, updates, and removal, and the installation notes cover all three platforms while disclosing installer effects. Naming is generally stable and examples are extensive, but there is no structured FAQ or substantial troubleshooting section. Cross-compilation, platform, medical-use, and rate-limit constraints are stated, though security, privacy, and resource limitations are not collected systematically. The complete MIT text agrees with project metadata. Version notes stop at v0.5.0 while pyproject declares v0.7.5, leaving the current changes undocumented. Maintenance is attributable to Byteflow.bot with an Issues link and contribution invitation, but no named maintainer, support policy, or response expectations are supplied.
The described desktop states, audio cues, HUD, CLI inspection, memory injection, and repository alerts are directly usable in a development workflow, and tests cover some important behaviors. Deductions apply because most core implementation and representative outputs are absent, preventing static confirmation of the full experience, while much of the incremental-value case rests on README claims. Local processing, ETag use, and API-rate budgeting address some costs, but background resource usage, notification burden, installation complexity, and ongoing maintenance cost are not quantified.
Some claims trace to package metadata, CI definitions, and focused tests covering context limits, determinism, authorization, and notification cooldowns; the architecture and primary data path are also explicitly stated. Deductions apply because core application files, installer scripts, and the complete test inventory are absent, so screenshots and README assertions cannot cross-corroborate runtime behavior. The 112-test claim, platform coverage, research basis, and several guarantees lack independent support in the supplied material. Facts, design statements, and the medical disclaimer are mostly distinguished, but marketing absolutes remain mixed with verifiable technical claims.
- Installation modifies ~/.claude/settings.json, creates a virtual environment, installs system graphics dependencies, and starts a background application; review the installers and back up existing Claude configuration first.
- Recommended GitHub PAT scopes, file permissions, encryption status, and log handling are not documented in the evidence; use a least-privilege token and verify how it is stored and protected.
- Automatic memory and context injection process project activity and notes. Do not rely solely on the asserted 11 regular expressions to keep secrets off disk; inspect the redaction implementation and database contents before enabling it for sensitive work.
- The README and package metadata disagree on the version, and dependencies are not locked. Pin the revision and resolved dependencies before deployment because release artifacts may not correspond cleanly to the documentation.
- The ergonomics features are not medical advice, and the supplied material contains no traceable research citations; seek professional guidance for pain or medical conditions.
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.