{"id":50125527,"url":"https://github.com/alvinunreal/openpets","last_synced_at":"2026-05-30T01:30:29.735Z","repository":{"id":355838085,"uuid":"1229168545","full_name":"alvinunreal/openpets","owner":"alvinunreal","description":"Desktop pets for AI coding agents. Install pets, connect Claude Code via MCP, and see live coding status on your desktop.","archived":false,"fork":false,"pushed_at":"2026-05-27T13:13:37.000Z","size":31526,"stargazers_count":948,"open_issues_count":8,"forks_count":32,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-27T14:17:44.955Z","etag":null,"topics":["ai-agents","bun","claude-code","coding-agents","desktop-pet","electron","mcp","opencode","openpets","pixel-art"],"latest_commit_sha":null,"homepage":"https://openpets.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alvinunreal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-04T19:14:46.000Z","updated_at":"2026-05-27T14:12:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alvinunreal/openpets","commit_stats":null,"previous_names":["alvinunreal/openpets"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/alvinunreal/openpets","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvinunreal%2Fopenpets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvinunreal%2Fopenpets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvinunreal%2Fopenpets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvinunreal%2Fopenpets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alvinunreal","download_url":"https://codeload.github.com/alvinunreal/openpets/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alvinunreal%2Fopenpets/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33677258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bun","claude-code","coding-agents","desktop-pet","electron","mcp","opencode","openpets","pixel-art"],"created_at":"2026-05-23T20:00:20.650Z","updated_at":"2026-05-30T01:30:29.729Z","avatar_url":"https://github.com/alvinunreal.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/openpets.png\" alt=\"OpenPets - pixel art desktop companion\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA tiny desktop companion that keeps you company.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  A playful pet that lives on your desktop, keeps you company, and can grow with bundled abilities and developer integrations.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/intro.png\" alt=\"OpenPets reacting across multiple coding agent sessions\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e\u003csub\u003eby \u003cb\u003eBoring Dystopia Development\u003c/b\u003e\u003c/sub\u003e\u003c/p\u003e\n  \u003cp\u003e\n    \u003ca href=\"https://boringdystopia.ai/\"\u003e\u003cimg src=\"https://img.shields.io/badge/boringdystopia.ai-111111?style=for-the-badge\u0026logo=vercel\u0026logoColor=white\" alt=\"boringdystopia.ai\"\u003e\u003c/a\u003e\u0026nbsp;\n    \u003ca href=\"https://x.com/alvinunreal\"\u003e\u003cimg src=\"https://img.shields.io/badge/X-@alvinunreal-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white\" alt=\"X @alvinunreal\"\u003e\u003c/a\u003e\u0026nbsp;\n    \u003ca href=\"https://t.me/boringdystopiadevelopment\"\u003e\u003cimg src=\"https://img.shields.io/badge/Telegram-Join%20channel-2CA5E0?style=for-the-badge\u0026logo=telegram\u0026logoColor=white\" alt=\"Telegram Join channel\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n---\n\n## 2-minute Quick Start\n\nDownload and launch the desktop app from [OpenPets Releases](https://github.com/alvinunreal/openpets/releases/latest). A companion pet appears immediately; bundled abilities make it feel alive without requiring an agent setup.\n\nIf you also want coding-agent integration, install the OpenPets Agent Skill with [skills.sh](https://skills.sh/):\n\n```bash\nnpx skills add alvinunreal/openpets --skill openpets\n```\n\nThen open Claude Code, OpenCode, Codex, or another skill-aware agent and say:\n\n```text\nUse the OpenPets skill. Install OpenPets for me, connect this agent, and verify the integration works.\n```\n\nFor project setup, open your agent inside the repo and say:\n\n```text\nUse the OpenPets skill. Help me choose or install a pet, configure it for this project, and verify the project integration.\n```\n\nUseful prompts:\n\n```text\nUse the OpenPets skill. Configure this project for Claude Code with a pet.\nUse the OpenPets skill. Configure this project for OpenCode with a pet.\nUse the OpenPets skill. Debug why openpets_status is unavailable.\n```\n\n## Star OpenPets\n\nHere is an extra GIF of me starring my own repo to encourage you to do the same. If OpenPets makes your coding setup a little more fun, please give the repo a star.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/star-repo.gif\" alt=\"Starring the OpenPets repository\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n## What is OpenPets?\n\nOpenPets is a tray-first desktop companion app. A pet appears on your desktop, keeps you company, and can use bundled abilities for ambient presence, breaks, playful actions, and focus sessions. Coding-agent integrations are still supported as an advanced developer layer.\n\n- **Desktop companion** - a small pet that idles, reacts, and gives OpenPets a friendly presence even before developer tools are configured.\n- **Bundled abilities** - first-party plugins can add ambient check-ins, break nudges, playful pet actions, focus timers, safe little walks, and optional developer notifications.\n- **Developer integrations** - advanced setup for Claude Code, OpenCode, Cursor, Pi, and MCP-capable tools when you want coding activity to drive the pet.\n- **MCP ready** - any MCP-capable agent can send short safe speech bubbles and reactions through the OpenPets MCP server.\n- **Pet-pack friendly** - loads installed animated pet packs and can route a selected agent/project to its own pet window.\n- **Privacy-conscious by design** - automatic hook speech is static and local; prompts, code, logs, command output, URLs, paths, and secrets are not shown in bubbles.\n\n## Manage your pets\n\nBrowse installed pets, preview their animations, and choose which companion should follow each coding agent from the OpenPets desktop app.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/manage-pets.png\" alt=\"Managing pets in the OpenPets desktop app\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n## Quick start\n\nInstall the desktop app, then optionally connect your coding agent.\n\n### 1. Install OpenPets Desktop\n\nDownload the latest app from [OpenPets Releases](https://github.com/alvinunreal/openpets/releases/latest):\n\n- **macOS Apple Silicon**: `OpenPets-*-mac-arm64.dmg`\n- **macOS Intel**: `OpenPets-*-mac-x64.dmg`\n- **Windows**: `OpenPets-*-win-x64-setup.exe`\n- **Linux**: `OpenPets-*-linux-x86_64.AppImage`\n\nLaunch OpenPets. You should see the desktop pet and the OpenPets tray/menu-bar icon.\n\n\u003e Current builds may be unsigned. macOS or Windows may show a security warning the first time you open the app.\n\nIf macOS says the app is damaged or should be moved to Trash, remove the quarantine flag and open it again:\n\n```bash\nxattr -dr com.apple.quarantine /Applications/OpenPets.app\nopen /Applications/OpenPets.app\n```\n\n### 2. Optional: connect your agent\n\nUse the desktop **Integrations** screen for global setup when available:\n\n- **Claude Code** - installs OpenPets MCP, Claude memory instructions, and optional Claude hooks.\n- **OpenCode** - installs OpenPets MCP, an OpenCode instruction file, and the `@open-pets/opencode` plugin.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/integrations.png\" alt=\"OpenPets desktop integrations screen\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\nFor project-local setup, run the CLI from the project you want to configure:\n\n```bash\nnpx -y @open-pets/cli@latest configure --agent claude --pet \u003cpetId\u003e\nnpx -y @open-pets/cli@latest configure --agent opencode --pet \u003cpetId\u003e\n```\n\nIf you prefer a permanent `openpets` shell command, install the CLI once with `npm install -g @open-pets/cli` and replace `npx -y @open-pets/cli@latest` with `openpets`.\n\nProject-local setup can create project files such as `.claude/settings.local.json` or `.opencode/opencode.jsonc`. Review them before committing because they may include the selected pet id.\n\n## Advanced: agent integrations\n\nOpenPets integrations have three layers:\n\n1. **MCP tools** for explicit agent actions.\n2. **Agent instructions** so agents know when to use those tools.\n3. **Hooks/plugins** for automatic decorative reactions during normal agent work.\n\n### Claude Code\n\nClaude Code integration supports:\n\n- `openpets` MCP setup via Claude Code.\n- Managed Claude memory instructions in `~/.claude/CLAUDE.md` and `~/.claude/openpets.md`.\n- Managed Claude hooks in `~/.claude/settings.json`.\n- Project-local setup through `npx -y @open-pets/cli@latest configure --agent claude --pet \u003cpetId\u003e` or the optional global `openpets` CLI.\n\nTypical global MCP command shape:\n\n```bash\nclaude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest\n```\n\nWith a selected pet:\n\n```bash\nclaude mcp add --scope user openpets -- npx -y @open-pets/mcp@latest --pet \u003cpetId\u003e\n```\n\nSee [`docs/claude-integration.md`](docs/claude-integration.md) for the full file layout, hook mapping, project-local behavior, and safety rules.\n\n### OpenCode\n\nOpenCode integration supports:\n\n- An MCP entry using `@open-pets/cli mcp`.\n- A managed `openpets.md` instruction file.\n- The `@open-pets/opencode` plugin for automatic reactions.\n- Global desktop setup and project-local `.opencode` setup.\n\nProject-local setup:\n\n```bash\nnpx -y @open-pets/cli@latest configure --agent opencode --pet \u003cpetId\u003e\n```\n\nSee [`docs/opencode.md`](docs/opencode.md) for global config selection, plugin behavior, project-local setup, and safety rules.\n\n### Generic MCP clients\n\nAny MCP-capable editor or coding agent can talk to OpenPets through the MCP server while the desktop app is running.\n\n```json\n{\n  \"mcpServers\": {\n    \"openpets\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@open-pets/mcp@latest\"]\n    }\n  }\n}\n```\n\nTo target a specific installed non-default pet:\n\n```json\n{\n  \"mcpServers\": {\n    \"openpets\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@open-pets/mcp@latest\", \"--pet\", \"\u003cpetId\u003e\"]\n    }\n  }\n}\n```\n\nAvailable MCP tools:\n\n- `openpets_status` - check whether OpenPets is reachable and which pet is targeted.\n- `openpets_react` - set a short reaction on the target pet.\n- `openpets_say` - show a short safe speech bubble, optionally with a reaction.\n\n`openpets_say` messages must be short, single-line, and must not look like code, logs, secrets, URLs, or file paths.\n\n## How it works\n\n```text\nClaude Code / OpenCode / Pi / MCP client\n  -\u003e @open-pets/mcp, @open-pets/cli mcp, @open-pets/claude hook, @open-pets/opencode plugin, or @open-pets/pi extension\n  -\u003e @open-pets/client\n  -\u003e OpenPets desktop local IPC discovery file\n  -\u003e OpenPets desktop IPC socket/pipe\n  -\u003e default pet or selected agent pet window\n```\n\nThe desktop app writes a local discovery file containing an IPC endpoint and a per-run token. Clients must send that token with every request.\n\nFor Windows desktop + WSL agent setups, see [`docs/wsl-ipc.md`](docs/wsl-ipc.md) for the opt-in TCP transport.\n\nWhen an integration is configured with `--pet \u003cpetId\u003e`, OpenPets asks the desktop app for a short-lived lease. Valid installed non-default pets open as explicit agent pet windows. Missing, invalid, broken, built-in, or default pet requests fall back to the desktop default pet.\n\n## Reactions and speech\n\nAutomatic hooks are decorative and best-effort. They do not approve, deny, block, or change agent behavior.\n\nCommon reaction mapping:\n\n| Agent activity | Reaction |\n| --- | --- |\n| Prompt/chat starts | `thinking` |\n| File edit/write/patch | `editing` |\n| Test-like shell command | `testing` |\n| Permission request | `waiting` |\n| Successful idle/stop | `success` |\n| Session/error stop | `error` |\n\nGeneric shell activity is intentionally quiet by default. Hook/plugin speech is throttled and selected from local static message pools such as `Approval needed` or `Something failed`.\n\n### Pi extension package\n\nOpenPets includes an experimental Pi extension package at `@open-pets/pi`. Pi support is extension-first rather than MCP-first: the extension listens to Pi lifecycle/tool events and sends local best-effort reactions through `@open-pets/client`.\n\n```bash\npi install npm:@open-pets/pi\npi install -l npm:@open-pets/pi\n```\n\nInside Pi, the extension registers `/openpets status`, `/openpets test`, `/openpets react \u003creaction\u003e`, and `/openpets say \u003cmessage\u003e`. Automatic events do not forward prompts, assistant text, tool output, file contents, paths, URLs, or secrets. Real Pi CLI install validation is still required before marking the integration fully supported.\n\n## Development\n\n### Requirements\n\n- Node.js 20+\n- pnpm 11+\n- TypeScript\n\nNo Bun runtime is required for development.\n\n### Install\n\n```bash\npnpm install\n```\n\n### Run the desktop app\n\n```bash\npnpm dev:desktop\n```\n\nEquivalent package command:\n\n```bash\npnpm --filter @open-pets/desktop dev\n```\n\n### Checks\n\n```bash\npnpm check\npnpm typecheck\npnpm build\npnpm test\n```\n\nOpenPets currently uses lightweight Node contract checks instead of a full test framework. See [`docs/testing.md`](docs/testing.md).\n\n### Package desktop builds\n\n```bash\npnpm package:desktop:dir\npnpm package:desktop\n```\n\nRelease process details live in [`docs/release.md`](docs/release.md).\n\n## Workspace layout\n\n```text\napps/desktop              Electron desktop app\npackages/client           @open-pets/client, local IPC client\npackages/mcp              @open-pets/mcp, MCP stdio server\npackages/claude           @open-pets/claude, Claude command and hook helpers\npackages/opencode         @open-pets/opencode, OpenCode config and plugin integration\npackages/pi               @open-pets/pi, Pi extension package\npackages/agent-events     Shared safe agent event speech helpers\npackages/cli              @open-pets/cli, user-run CLI and MCP/hook entrypoints\npackages/pet-format       @open-pets/pet-format, pet/catalog format types\ndocs/                     Documentation\n```\n\n## Documentation\n\n- [`docs/claude-integration.md`](docs/claude-integration.md) - Claude Code setup, MCP, memory, hooks, and safety.\n- [`docs/opencode.md`](docs/opencode.md) - OpenCode global/project setup, plugin behavior, and safety.\n- [`docs/wsl-ipc.md`](docs/wsl-ipc.md) - Windows desktop + WSL MCP transport setup.\n- [`docs/testing.md`](docs/testing.md) - test/check strategy.\n- [`docs/release.md`](docs/release.md) - desktop release process.\n- [`docs/workflow.md`](docs/workflow.md) - project workflow notes.\n\n## Safety and privacy notes\n\n- OpenPets local IPC is local-only and protected by a per-run token.\n- Hook/plugin errors are swallowed unless debug logging is enabled.\n- Automatic speech is static and local; it does not include model-generated prompt text.\n- Tool inputs and command text are used only for coarse reaction classification.\n- Managed setup preserves unrelated user config and removes only OpenPets-managed entries.\n- Speech validation rejects code-like, secret-like, URL-like, path-like, or multiline messages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falvinunreal%2Fopenpets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falvinunreal%2Fopenpets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falvinunreal%2Fopenpets/lists"}